# Quickstart

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

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.

```bash
export LYDIE_TOKEN="lyd_pat_..."
```

A token belongs to one workspace and acts as you. [Authentication](https://developers.lydie.co/authentication.md) explains what it
can and cannot do.

## 2. Find your workspace

```bash
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"
    }
  ]
}
```

```bash
export WORKSPACE="01JCQ3TZ0WJ8K4M2X7T9R6N1PA"
```

## 3. Create a document

```bash
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](https://developers.lydie.co/api/documents.md). A top-level page goes to your private section
unless you pass a `teamspaceId`. Keep its `id`:

```bash
export DOC="01JCQ3V5MZ8G4ZK2X7T9R6N1PB"
```

## 4. Read it

```bash
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:

```bash
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

- Connect an AI assistant instead: [MCP server](https://developers.lydie.co/mcp.md).
- How bodies, properties and links work: [Documents and Markdown](https://developers.lydie.co/documents.md).
- Every endpoint: [API reference](https://developers.lydie.co/api.md).