Skip to content
Engram Docs

Create or update a note

POST
/notes
curl --request POST \
  --url https://api.engram.page/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "# Engram\n\nAn AI-powered personal knowledge base.\n", "mtime": 1718900000, "path": "Projects/Engram.md", "tags": [ "project", "ai" ] }'

Creates a note or updates the existing one at the same path. Updates are merged convergently (CRDT) with the stored content. Optionally pass base_hash — the content_hash you last read — for compare-and-swap semantics: if the note changed since that read, the write returns 409 with the current server note instead of merging. Notes over 10MB are rejected with 413, and exceeding the plan’s note cap returns 402.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

Note to upsert

Media typeapplication/json
UpsertNoteRequest
object
base_hash

Compare-and-swap guard: the content_hash you last read for this note. If the note changed since, the write returns 409 instead of merging.

string
nullable
content
string
folder
string
nullable
mtime
required
number format: float
path
required
string
tags
Array<string>
title
string
nullable
version
integer
nullable
Example
{
  "content": "# Engram\n\nAn AI-powered personal knowledge base.\n",
  "mtime": 1718900000,
  "path": "Projects/Engram.md",
  "tags": [
    "project",
    "ai"
  ]
}

Responses

Section titled “Responses”

201

Section titled “201”

Created/updated

Media typeapplication/json
NoteResponse
object
note
required
Note
object
content
string
content_hash
string
nullable
description

OKF frontmatter description field

string
nullable
fm_created

OKF frontmatter created/date field

string format: date-time
nullable
fm_timestamp

OKF frontmatter timestamp/modified/updated field

string format: date-time
nullable
folder
string
nullable
id
string format: uuid
nullable
mtime

Client mtime (epoch seconds)

number format: float
parse_reason

Present when parse_status is “degraded”: {code, message, detail}

object
parse_status

Frontmatter parse outcome

string
nullable
Allowed values: ok degraded
path
required
string
resource

OKF frontmatter resource field

string
nullable
tags
Array<string>
title
string
nullable
type

OKF frontmatter type field

string
nullable
updated_at
string format: date-time
nullable
version
integer
nullable
Example
{
  "note": {
    "parse_status": "ok",
    "path": "Projects/engram.md"
  }
}

409

Section titled “409”

Version conflict

Media typeapplication/json
Conflict
object
error
string
server_note
Note
object
content
string
content_hash
string
nullable
description

OKF frontmatter description field

string
nullable
fm_created

OKF frontmatter created/date field

string format: date-time
nullable
fm_timestamp

OKF frontmatter timestamp/modified/updated field

string format: date-time
nullable
folder
string
nullable
id
string format: uuid
nullable
mtime

Client mtime (epoch seconds)

number format: float
parse_reason

Present when parse_status is “degraded”: {code, message, detail}

object
parse_status

Frontmatter parse outcome

string
nullable
Allowed values: ok degraded
path
required
string
resource

OKF frontmatter resource field

string
nullable
tags
Array<string>
title
string
nullable
type

OKF frontmatter type field

string
nullable
updated_at
string format: date-time
nullable
version
integer
nullable
Example
{
  "error": "version_conflict",
  "server_note": {
    "parse_status": "ok",
    "path": "Projects/engram.md"
  }
}

413

Section titled “413”

Note exceeds 10MB

Media typeapplication/json
Error
object
errors
One of:
string
Examplegenerated
{
  "errors": {}
}

422

Section titled “422”

Validation error

Media typeapplication/json
Error
object
errors
One of:
string
Examplegenerated
{
  "errors": {}
}