# KV Notes (/experiments/kv-notes)



Store and retrieve small text notes using a dedicated Workers KV namespace.

## API Endpoints [#api-endpoints]

### POST /notes [#post-notes]

Create or update a note.

**`id`** `string` (required)

Note identifier (letters, numbers, `_`, `-`; max 64 characters)

**`content`** `string` (required)

Note body (max 4,000 characters)

#### Example Request [#example-request]

```bash
curl -X POST "https://your-worker.workers.dev/notes" \
  -H "Content-Type: application/json" \
  -d '{"id":"todo-1","content":"Ship the experiment"}'
```

#### Success Response [#success-response]

```json
{
  "id": "todo-1",
  "content": "Ship the experiment",
  "updatedAt": "2025-06-20T12:00:00.000Z"
}
```

### GET /notes [#get-notes]

Fetch a note by id.

**`id`** `string` (required)

#### Example Request [#example-request-1]

```bash
curl "https://your-worker.workers.dev/notes?id=todo-1"
```

### DELETE /notes [#delete-notes]

Delete a note by id.

**`id`** `string` (required)

#### Error Codes [#error-codes]

* `400` - Invalid id or content (`INVALID_ID`, `INVALID_CONTENT`, `INVALID_BODY`)
* `404` - Note not found (`NOT_FOUND`)

## Use Cases [#use-cases]

* Learn KV read/write/delete patterns without D1
* Store small configuration blobs at the edge
* Prototype simple key-value APIs before adding auth

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/kv-notes)
  </Step>

  <Step>
    ### Configure KV [#configure-kv]

    Create a KV namespace and bind it as `NOTES` in `wrangler.json`.
  </Step>
</Steps>

## Local Development [#local-development]

```bash
cd apps/experiments/kv-notes
npm install
npm run dev
```

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Workers KV](https://developers.cloudflare.com/kv/)** - Global key-value storage