Forms, sheets and boards: API examples

The same call as in the ⚡ API quickstart, with a different tool name and arguments.

Forms

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forms","arguments":{"action":"list"}}}'

- Contact us (id: cmvkjzyk3000a7d1unhc4pys0, 0 responses, https://app.thenotemaker.com/f/contact-us-t4948j4u)

Read the newest responses that nobody has handled yet, then mark one as handled with a private note:

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forms","arguments":{"action":"responses","form_id":"cmvkjzyk3000a7d1unhc4pys0","status":"new","limit":5}}}'

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forms_write","arguments":{"action":"triage","form_id":"cmvkjzyk3000a7d1unhc4pys0","response_id":"RESPONSE_ID","handled":true,"note":"Answered by email"}}}'

A published form also accepts submissions from anyone, with no token, at POST /api/forms/<form id>/submit. A JSON body keyed by field id is enough; send an Idempotency-Key header and a retried submission stores one response, not two:

curl -s -X POST "https://app.thenotemaker.com/api/forms/cmvkjzyk3000a7d1unhc4pys0/submit" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Asha Rao","email":"asha@example.com","message":"Hello!"}'

{"ok":true}

A submission that fails validation answers HTTP 422 as application/problem+json, with ok, message and errors (field id → what is wrong) kept for older clients. Too many submissions answer 429 with Retry-After.

Sheets

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sheets","arguments":{"action":"list"}}}'

- Tasks (id: cmvkjzyk7000c7d1u1knfgn7w, 4 rows; columns: Task [text], Done [checkbox], Due [date], Priority [select], Estimate [number])

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sheets","arguments":{"action":"get","sheet_id":"cmvkjzyk7000c7d1u1knfgn7w","limit":2}}}'

Tasks: showing 2 of 4 rows from 0
- cmvkjzykp000n7d1uiuokky56: {"Task":"Task 1","Done":true,"Priority":"High","Estimate":1}
- cmvkjzykp000o7d1ugqs1jy6t: {"Task":"Task 2","Done":false,"Priority":"High","Estimate":2}

Values are keyed by column name. An unknown name fails the whole call and nothing is written. A locked sheet answers This sheet is locked.

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sheets_write","arguments":{"action":"add_rows","sheet_id":"cmvkjzyk7000c7d1u1knfgn7w","rows":[{"Task":"Write docs","Done":false,"Priority":"High"}]}}}'

Boards and cards

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"boards","arguments":{"action":"list"}}}'

- Pipeline (id: cmvkjzykd000g7d1u8d3ywvfu; states: To do 1, In progress 1, Done 0)

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"boards","arguments":{"action":"get","board_id":"cmvkjzykd000g7d1u8d3ywvfu","limit":3}}}'

Pipeline: To do 1, In progress 1, Done 0
- PIP-1 First card [To do] {Bug, Improvement, Docs} (id: cmvkjzykj000k7d1ujhh79byk)
- PIP-2 Second card [In progress] {Bug} (id: cmvkjzykm000m7d1udij4hjd2)

Filter the cards with query, assignee (me, nobody or a name), label, due and where. A card can be named by its key, such as PIP-3:

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"boards_write","arguments":{"action":"create_card","board_id":"cmvkjzykd000g7d1u8d3ywvfu","title":"Try the API","state":"To do"}}}'

Added card PIP-3 "Try the API" to To do on "Pipeline" (id: cmvp00…)

curl -s -X POST "$NOTEMAKER_URL" \
  -H "Authorization: Bearer $NOTEMAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"boards_write","arguments":{"action":"move_card","board_id":"cmvkjzykd000g7d1u8d3ywvfu","card_id":"PIP-3","state":"In progress"}}}'

Moved the card to In progress on "Pipeline".

Creating a card twice makes two cards. Send an Idempotency-Key with create_card and a retry after a timeout gets the first answer back instead.