Skip to content
Engram Docs

Upsert up to 100 notes (idempotent via X-Idempotency-Key)

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

Creates or updates up to 100 notes in one request, returning a per-note result (ok, conflict, or error) so a single bad or oversized (>10MB) note does not fail the batch. More than 100 notes returns 400, and exceeding the plan’s note cap returns 402. Requires the X-Idempotency-Key header for safe retries.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

Notes array

Media typeapplication/json
BatchUpsertRequest
object
notes
required
Array<object>
<= 100 items
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"
  ]
}
Example
{
  "notes": [
    {
      "content": "# Engram\n\nAn AI-powered personal knowledge base.\n",
      "mtime": 1718900000,
      "path": "Projects/Engram.md",
      "tags": [
        "project",
        "ai"
      ]
    },
    {
      "content": "## 2026-06-20\n\n- Shipped the batch upsert endpoint.\n",
      "mtime": 1718900100,
      "path": "Daily/2026-06-20.md"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Per-note results

Media typeapplication/json
BatchUpsertResponse
object
results
required
Array<object>
BatchUpsertResult
object
content_hash
string
nullable
errors
object
id
string format: uuid
nullable
parse_reason

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

object
parse_status

Frontmatter parse outcome

string
nullable
Allowed values: ok degraded
path
string
server_note
One of:
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
server_path
string
nullable
status
string
Allowed values: ok conflict error
version
integer
nullable
Example
{
  "results": [
    {
      "parse_status": "ok",
      "server_note": {
        "parse_status": "ok",
        "path": "Projects/engram.md"
      },
      "status": "ok"
    }
  ]
}

400

Section titled “400”

Invalid array / >100 items

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