REST API Quick Start

This API now has a deliberately smaller public surface. The primary execution boundary is /v1/flow; explicit note endpoints remain for straightforward CRUD, context, versions, export, and health.

Setup

export KEEPNOTES_API_KEY="kn_your_api_key_here"
export KEEPNOTES_URL="https://api.keepnotes.ai"

All endpoints except /v1/ready and /v1/health require:

Authorization: Bearer kn_your_api_key_here

If your organization uses multiple projects, include:

X-Project: your-project-slug

Primary Interface: Flows

keep itself talks to the hosted service primarily through /v1/flow. Use it when you want the same stable state-doc execution model as the current remote client.

Query Memory

curl -s "$KEEPNOTES_URL/v1/flow" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "query-resolve",
    "params": {"query": "booking flights for Kate"},
    "writable": false
  }' | jq

Get Context For One Item

curl -s "$KEEPNOTES_URL/v1/flow" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "get",
    "params": {"item_id": "now"},
    "writable": false
  }' | jq

Store A Note Through The Flow Runtime

curl -s "$KEEPNOTES_URL/v1/flow" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "put",
    "params": {
      "id": "travel/preferences",
      "content": "Kate prefers aisle seats"
    }
  }' | jq

Explicit Note Operations

These are the retained convenience endpoints. They are intentionally narrower than the old REST surface.

Store A Note

curl -s "$KEEPNOTES_URL/v1/notes" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Kate prefers aisle seats"}' | jq

Get A Note

curl -s "$KEEPNOTES_URL/v1/notes/travel%2Fpreferences" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

List Notes

curl -s "$KEEPNOTES_URL/v1/notes?limit=20&include_hidden=false" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Get Unified Context

curl -s "$KEEPNOTES_URL/v1/notes/travel%2Fpreferences/context?similar_limit=5&meta_limit=3" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Update Tags

curl -s -X PATCH "$KEEPNOTES_URL/v1/notes/travel%2Fpreferences/tags" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"set":{"person":"kate","topic":"travel"}}' | jq

Revert To A Previous Version

curl -s -X POST "$KEEPNOTES_URL/v1/notes/travel%2Fpreferences/revert" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Analyze A Document Into Parts

curl -s -X POST "$KEEPNOTES_URL/v1/notes/travel%2Fpolicy/analyze" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq

Retrieve parts later:

curl -s "$KEEPNOTES_URL/v1/notes/travel%2Fpolicy/parts" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Current Working Context

curl -s "$KEEPNOTES_URL/v1/now" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

curl -s -X PUT "$KEEPNOTES_URL/v1/now" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Finish contract cleanup"}' | jq

Prompts

List available prompts:

curl -s "$KEEPNOTES_URL/v1/prompts" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Render one with memory context:

curl -s -X POST "$KEEPNOTES_URL/v1/prompts" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"reflect","id":"now"}' | jq

Export And Import

Full JSON snapshot:

curl -s "$KEEPNOTES_URL/v1/export" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Streaming NDJSON snapshot:

curl -s "$KEEPNOTES_URL/v1/export?stream=ndjson" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY"

Single-note bundle:

curl -s "$KEEPNOTES_URL/v1/export/bundles/travel%2Fpreferences" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Incremental change feed:

curl -s "$KEEPNOTES_URL/v1/export/changes?cursor=0&limit=100" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" | jq

Import a keep-export snapshot:

curl -s -X POST "$KEEPNOTES_URL/v1/import" \
  -H "Authorization: Bearer $KEEPNOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d @export.json | jq

Health And Readiness

Readiness and capabilities:

curl -s "$KEEPNOTES_URL/v1/ready" | jq

Health and current item count:

curl -s "$KEEPNOTES_URL/v1/health" | jq

Supported Endpoint Inventory

Section	Methods
Flow	`POST /v1/flow`, `GET /v1/prompts`, `POST /v1/prompts`
Notes	`POST /v1/notes`, `GET /v1/notes`, `GET /v1/notes/{note_id}`, `DELETE /v1/notes/{note_id}`, `PATCH /v1/notes/{note_id}/tags`
Versions	`GET /v1/notes/{note_id}/versions`, `GET /v1/notes/{note_id}/versions/{offset}`, `POST /v1/notes/{note_id}/revert`
Context	`GET /v1/notes/{note_id}/context`, `GET /v1/now`, `PUT /v1/now`, `GET /v1/now/context`
Analysis	`POST /v1/notes/{note_id}/analyze`, `GET /v1/notes/{note_id}/parts`, `GET /v1/notes/{note_id}/parts/{part_num}`
Movement	`POST /v1/move`
Transfer	`GET /v1/export`, `GET /v1/export/bundles/{note_id}`, `GET /v1/export/changes`, `POST /v1/import`
Health	`GET /v1/ready`, `GET /v1/health`

Intentionally Unsupported Legacy Endpoints

The public contract no longer includes dedicated REST shims for:

/v1/search
/v1/tags
/v1/notes/{note_id}/resolve
/v1/notes/{note_id}/status
/v1/count
/v1/collections
/v1/tasks
/v1/processors

Use /v1/flow, /v1/notes/{note_id}/context, and /v1/health instead.