# OpenPad CLI/agent guide

Base URL: `http://openpad.nikv.me`

Use URL paths as document names (for example `/ideas`, `/project-notes`).

## Read and write documents

- Write markdown: `PUT /:name` with `Content-Type: text/markdown`
- Read markdown: `GET /:name/markdown` (or `GET /:name` with `Accept: text/markdown`)
- Read plain text: `GET /:name/plain`
- Read JSON: `GET /:name/json`

## Media upload

- Upload image/file: `POST /:name/media` as multipart form-data field `file`
- Use returned `url` inside markdown as `[image:/name/media/file]`

## Auth and protection notes

- This instance currently requires global authentication for at least some actions. Use the web login flow once per browser/client session before editing protected pages.
- Per-page locks may require page passwords for view/edit depending on mode.
- Global and page auth can stack.
- Browser-style sessions are cookie based; API clients should preserve cookies if they need repeated authenticated operations.

## Examples

```bash
# Write markdown
curl -X PUT 'http://openpad.nikv.me/ideas' \
  -H 'Content-Type: text/markdown' \
  --data-binary $'# Ideas\n\n- one\n- two\n'

# Read markdown
curl -H 'Accept: text/markdown' 'http://openpad.nikv.me/ideas'

# Upload media
curl -X POST 'http://openpad.nikv.me/ideas/media' \
  -F 'file=@/path/to/image.png'
```

Tip: request `/` with `Accept: application/markdown` to force this guide response.