Skip to content

API.md

Latest commit

 

History

History
445 lines (320 loc) · 8.04 KB

API.md

File metadata and controls

445 lines (320 loc) · 8.04 KB

Strata HTTP API Guide

Local API CLI Security

Practical reference for tools and agents that create, read, update, and delete Strata notes.

Quick Facts

  • Base URL: http://127.0.0.1:3939
  • API is available only while Strata is running.
  • Data is local-only (SQLite in Strata userData).
  • Optional auth: set STRATA_API_TOKEN before launching Strata.

Quick Start

CLI:

npm run strata -- health
npm run strata -- notes list --json
npm run strata -- notes create --content "# Title\n\nBody"

curl:

curl http://127.0.0.1:3939/health
curl "http://127.0.0.1:3939/notes?query=project"

For full CLI command coverage, see CLI.md.

Authentication and Headers

Required for write operations:

  • Content-Type: application/json for POST, PUT, PATCH

If auth is enabled, send one of:

  • X-Strata-Token: <token>
  • Authorization: Bearer <token>

Header examples:

-H "X-Strata-Token: your-secret-token"
# or
-H "Authorization: Bearer your-secret-token"

Endpoint Index

  • GET /health
  • GET /notes
  • GET /notes/:id
  • POST /notes
  • PUT /notes/:id
  • PATCH /notes/:id
  • DELETE /notes/:id
  • GET /tags
  • GET /search
  • GET /notes/:id/backlinks
  • GET /notes/:id/related
  • GET /notes/:id/ai-edits
  • POST /ai-edits/:id/revert

Endpoints

Health Check

GET /health

curl http://127.0.0.1:3939/health

Response:

{"ok":true}

List Notes

GET /notes

Optional query params:

  • query (string)
  • starred (true or false)
  • archived (true or false)
  • tag (string)
  • includeDeleted (true or false)

Examples:

curl http://127.0.0.1:3939/notes
curl "http://127.0.0.1:3939/notes?query=project&starred=true"
curl "http://127.0.0.1:3939/notes?tag=automation&archived=false"

Response shape:

{
  "notes": [
    {
      "id": "uuid",
      "content": "# Title\n\nBody",
      "createdAt": "2026-03-03T22:57:50.032Z",
      "updatedAt": "2026-03-03T22:57:50.034Z",
      "starred": false,
      "archived": false,
      "tags": ["api"],
      "deletedAt": null
    }
  ]
}

Get One Note

GET /notes/:id

curl http://127.0.0.1:3939/notes/<NOTE_ID>

Response:

{
  "note": {
    "id": "uuid",
    "content": "# Title\n\nBody",
    "createdAt": "2026-03-03T22:57:50.032Z",
    "updatedAt": "2026-03-03T22:57:50.034Z",
    "starred": false,
    "archived": false,
    "tags": ["api"],
    "deletedAt": null
  }
}

Create Note

POST /notes

Body fields are optional:

  • content: string
  • starred: boolean
  • archived: boolean
  • tags: string[]

Examples:

# Create with defaults
curl -X POST http://127.0.0.1:3939/notes \
  -H "Content-Type: application/json" \
  -d '{}'

# Create with content/tags
curl -X POST http://127.0.0.1:3939/notes \
  -H "Content-Type: application/json" \
  -d '{"content":"# New note\n\nCreated by API","tags":["api","agent"]}'

Response:

{"note": {"id": "uuid", "content": "...", "tags": ["api", "agent"], "starred": false, "archived": false, "createdAt": "...", "updatedAt": "...", "deletedAt": null}}

Update Note

PUT /notes/:id or PATCH /notes/:id

Body fields (any subset):

  • content: string
  • starred: boolean
  • archived: boolean
  • tags: string[]

Examples:

# Update content
curl -X PATCH http://127.0.0.1:3939/notes/<NOTE_ID> \
  -H "Content-Type: application/json" \
  -d '{"content":"# Updated\n\nRewritten content"}'

# Star and retag
curl -X PATCH http://127.0.0.1:3939/notes/<NOTE_ID> \
  -H "Content-Type: application/json" \
  -d '{"starred":true,"tags":["important","api"]}'

Response:

{"note": {"id": "uuid", "content": "...", "tags": ["important", "api"], "starred": true, "archived": false, "createdAt": "...", "updatedAt": "...", "deletedAt": null}}

Delete Note

DELETE /notes/:id

curl -X DELETE http://127.0.0.1:3939/notes/<NOTE_ID>

Response:

{"deleted":true}

Common Agent Workflows

1) Create and keep returned ID

curl -sS -X POST http://127.0.0.1:3939/notes \
  -H "Content-Type: application/json" \
  -d '{"content":"# Agent note\n\nBody","tags":["agent"]}'

Read note.id from the response and store it for future updates.

2) Upsert pattern (find by query, then create/update)

  1. GET /notes?query=<text>
  2. If match found, PATCH /notes/:id
  3. If no match, POST /notes

3) Toggle archive/star

curl -X PATCH http://127.0.0.1:3939/notes/<NOTE_ID> \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

curl -X PATCH http://127.0.0.1:3939/notes/<NOTE_ID> \
  -H "Content-Type: application/json" \
  -d '{"starred":true}'

Error Handling

Typical statuses:

  • 200 success
  • 201 created
  • 204 preflight (OPTIONS)
  • 400 invalid JSON or validation failure
  • 401 invalid/missing token (when auth enabled)
  • 404 note/route not found
  • 405 method not allowed
  • 413 body too large (>1MB)
  • 500 internal server error

Validation error shape:

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["tags"],
      "message": "Expected array, received string"
    }
  ]
}

Tags

GET /tags

Returns all tags with counts.

curl http://127.0.0.1:3939/tags

Response:

{
  "tags": [
    { "name": "demo", "count": 3 },
    { "name": "features", "count": 1 }
  ]
}

Search Notes

GET /search?q=...&limit=25

Full-text search across note content and tags.

Param Description Default
q Search query (required) —
limit Max results (1-100) 25 
curl "http://127.0.0.1:3939/search?q=wiki+links&limit=5"

Response:

{ "notes": [{ "id": "uuid", "content": "...", ... }] }

Backlinks

GET /notes/:id/backlinks

curl http://127.0.0.1:3939/notes/<NOTE_ID>/backlinks

Response:

{
  "backlinks": [
    {
      "link": { "id": "link-id", "sourceNoteId": "uuid", "rawTarget": "My Note", "label": null },
      "source": { "id": "uuid", "content": "# Source\n\n[[My Note]]", ... }
    }
  ]
}

Related Notes

GET /notes/:id/related

curl http://127.0.0.1:3939/notes/<NOTE_ID>/related

Response:

{
  "related": [
    { "note": { "id": "uuid", ... }, "reason": "Links here, Shared tags", "score": 60 }
  ]
}

AI Edit History

GET /notes/:id/ai-edits

curl http://127.0.0.1:3939/notes/<NOTE_ID>/ai-edits

Response:

{
  "edits": [
    { "id": "edit-id", "noteId": "uuid", "action": "update", "beforeContent": "...", "afterContent": "...", "revertedAt": null }
  ]
}

Revert AI Edit

POST /ai-edits/:id/revert

curl -X POST http://127.0.0.1:3939/ai-edits/<EDIT_ID>/revert

Response: { "reverted": true }

Using the Included CLI Helper

Strata ships with a wrapper script:

npm run notes:api -- health
npm run notes:api -- list
npm run notes:api -- get <NOTE_ID>
npm run notes:api -- create '{"content":"# Via helper"}'
npm run notes:api -- update <NOTE_ID> '{"starred":true}'
npm run notes:api -- delete <NOTE_ID>
npm run notes:api -- tags
npm run notes:api -- search "wiki links"
npm run notes:api -- backlinks <NOTE_ID>
npm run notes:api -- related <NOTE_ID>
npm run notes:api -- ai-edits <NOTE_ID>
npm run notes:api -- revert-edit <EDIT_ID>

Helper env vars:

  • STRATA_API_BASE_URL (default http://127.0.0.1:3939)
  • STRATA_API_TOKEN (optional)

Operational Notes

  • Keep Strata running while your agent uses the API.
  • External API writes trigger automatic UI refresh in the app.
  • If auth is required, launch Strata with STRATA_API_TOKEN set in the environment.
  • This API intentionally does not expose shell command execution endpoints.
  • Publisher shell execution is available only through preload IPC (window.strata.shell.run) inside the app context.