Skip to content
LydieDevelopers
Menu

Quickstart

Create an API token, find your workspace, and create, read and edit a document with the REST API.

View as Markdown

This takes about five minutes with curl. You need a Lydie account and a workspace.

1. Create an API token

In Lydie, open Settings → Agents & API. Under Hosted API, give a token a name and create it. Copy the secret, which starts with lyd_pat_. Lydie shows it once.

Terminal
export LYDIE_TOKEN="lyd_pat_..."

A token belongs to one workspace and acts as you. Authentication explains what it can and cannot do.

2. Find your workspace

Terminal
curl https://api.lydie.co/v1/workspaces \
  -H "Authorization: Bearer $LYDIE_TOKEN"

A token sees only its own workspace, so the list has one entry:

JSON
{
  "workspaces": [
    {
      "id": "01JCQ3TZ0WJ8K4M2X7T9R6N1PA",
      "name": "Notes",
      "role": "owner",
      "createdAt": "2026-11-12T09:30:00.000Z",
      "updatedAt": "2026-11-12T09:30:00.000Z"
    }
  ]
}
Terminal
export WORKSPACE="01JCQ3TZ0WJ8K4M2X7T9R6N1PA"

3. Create a document

Terminal
curl -X POST https://api.lydie.co/v1/documents \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE"'",
    "title": "Meeting notes",
    "markdown": "# Meeting notes\n\n- Ship the developer docs"
  }'

The response is the new document. A top-level page goes to your private section unless you pass a teamspaceId. Keep its id:

Terminal
export DOC="01JCQ3V5MZ8G4ZK2X7T9R6N1PB"

4. Read it

Terminal
curl https://api.lydie.co/v1/documents/$DOC \
  -H "Authorization: Bearer $LYDIE_TOKEN"
JSON
{
  "document": { "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB", "title": "Meeting notes", "...": "..." },
  "body": {
    "markdown": "# Meeting notes\n\n- Ship the developer docs",
    "version": "c2f1…"
  }
}

5. Edit it

Send exact replacements instead of the whole body. Include the version you read, so the edit fails with 409 conflict if someone changed the page in the meantime:

Terminal
curl -X PATCH https://api.lydie.co/v1/documents/$DOC/body \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "edits": [{ "oldStr": "Ship the developer docs", "newStr": "Shipped the developer docs" }],
    "expectedVersion": "c2f1…"
  }'

If someone has the page open, they see the change appear. An edit that does not match exactly once is skipped and listed in warnings.

Next