---
title: REST with curl
description: A tour of the openmemory REST API with curl - space, facts, journal, records, approvals, KV, events, batch, and forget.
---

Every example assumes:

```bash
export OM=https://api.openmemory.sh
export OPENMEMORY_KEY="om_..."   # from POST /v1/spaces
AUTH="Authorization: Bearer $OPENMEMORY_KEY"
JSON='content-type: application/json'
```

## Space

```bash
curl -s -X POST $OM/v1/spaces -H "$JSON" -d '{"timezone":"Europe/Athens"}'   # no auth
curl -s $OM/v1/space -H "$AUTH"                                               # usage and limits
curl -s -X PATCH $OM/v1/space -H "$AUTH" -H "$JSON" -d '{"dream_mode":"client"}'
curl -s $OM/v1/export -H "$AUTH" > openmemory-export.json
```

## Facts

```bash
curl -s -X POST $OM/v1/memories -H "$AUTH" -H "$JSON" \
  -d '{"subject":"Ana","text":"Runs the Lisbon office","origin":"user","tags":["work"]}'

curl -s "$OM/v1/memories?q=lisbon&limit=5" -H "$AUTH"
curl -s "$OM/v1/memories?subject=Ana" -H "$AUTH"
curl -s -X PATCH $OM/v1/memories/mem_... -H "$AUTH" -H "$JSON" -d '{"tier":"core"}'
```

## Journal

```bash
curl -s -X PUT $OM/v1/journal/2026-11-01 -H "$AUTH" -H "$JSON" \
  -d '{"summary":"Reviewed Q4 plan","open_loops":["Send Ana the budget"],"merge":true}'
curl -s "$OM/v1/journal?from=2026-10-25" -H "$AUTH"
```

## Records

```bash
curl -s -X POST $OM/v1/collections/commitments/records -H "$AUTH" -H "$JSON" \
  -d '{"key":"budget-ana","status":"open","due_at":"2026-11-04T09:00:00Z","data":{"what":"Send Ana the budget"}}'

curl -s "$OM/v1/collections/commitments/records?status=open" -H "$AUTH"

curl -s -X PATCH $OM/v1/collections/commitments/records/rec_... -H "$AUTH" -H "$JSON" \
  -d '{"status":"done","expected_version":1}'
```

## Approvals

```bash
curl -s -X POST $OM/v1/actions -H "$AUTH" -H "$JSON" \
  -d '{"class":"email_send","summary":"Send Ana the Q4 budget","payload":{"to":"ana@example.com","attachment":"q4.xlsx"},"idempotency_key":"budget-ana-1"}'
# -> {"action":{"id":"A1","status":"pending",...},"created":true}

curl -s -X POST $OM/v1/actions/A1/transition -H "$AUTH" -H "$JSON" -d '{"from":"pending","to":"approved"}'
curl -s -X POST $OM/v1/actions/A1/transition -H "$AUTH" -H "$JSON" -d '{"from":"approved","to":"executing"}'
curl -s -X POST $OM/v1/actions/A1/transition -H "$AUTH" -H "$JSON" \
  -d '{"from":"executing","to":"done","receipt":{"message_id":"<id from your mail API>"}}'
```

If another worker already moved A1, the transition returns `409` with `current_status` in `error.details`.

## KV and events

```bash
curl -s -X PUT $OM/v1/kv/cursors/gmail -H "$AUTH" -H "$JSON" -d '{"value":{"history_id":4411},"expected_version":0}'
curl -s $OM/v1/kv/cursors -H "$AUTH"
curl -s -X POST $OM/v1/events -H "$AUTH" -H "$JSON" -d '{"kind":"run","key":"daily-brief","status":"ok"}'
curl -s "$OM/v1/events?kind=run&limit=10" -H "$AUTH"
```

## Context and batch

```bash
curl -s "$OM/v1/context?budget_chars=3000&kv=settings&collections=commitments" -H "$AUTH"

curl -s -X POST $OM/v1/batch -H "$AUTH" -H "$JSON" -d '{
  "ops": [
    {"op":"memory.remember","input":{"text":"Ana prefers budgets as PDF","origin":"user"}},
    {"op":"journal.put","date":"2026-11-01","input":{"summary":"Sent the budget","merge":true}},
    {"op":"event.append","input":{"kind":"run","status":"ok"}}
  ]
}'
```

## Forget

```bash
curl -s -X POST $OM/v1/forget -H "$AUTH" -H "$JSON" -d '{"query":"Ana","scopes":["memories","records","journal"],"dry_run":true}'
```

Remove `dry_run` to delete. See [Forget and privacy](/docs/forget-and-privacy).

## Related

- [API reference](/docs/api-reference).