# Forms, sheets and boards: API examples

The same call as in the [⚡ API quickstart](https://docs.wrightdesk.com/build-with-the-api/api-quickstart), with a different tool name and arguments.

## Forms

```bash
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"}}}'
```

```text
- 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:

```bash
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}}}'
```

```bash
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:

```bash
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!"}'
```

```json
{"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

```bash
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"}}}'
```

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

```bash
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}}}'
```

```text
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.`

```bash
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

```bash
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"}}}'
```

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

```bash
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}}}'
```

```text
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`:

```bash
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"}}}'
```

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

```bash
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"}}}'
```

```text
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.