# Lydie Developers

> Lydie is a writing app for notes and documents in plain Markdown, alone or with a team. Its REST API and MCP server let scripts and AI agents read, write and organise the pages of a hosted workspace.

Notes for agents:

- REST base URL: https://api.lydie.co/v1. MCP server (Streamable HTTP): https://api.lydie.co/mcp. Prefer MCP when you are an AI assistant.
- Authenticate with `Authorization: Bearer <token>`: a personal API token (`lyd_pat_…`) or an OAuth access token. A token belongs to one workspace and has the scopes `docs:read` and/or `docs:write`.
- Document bodies are Markdown (CommonMark + GFM + wikilinks). To edit, prefer `edits` (exact oldStr/newStr replacements) over replacing the whole body, and pass `expectedVersion` from the last read.
- Your changes are recorded as an agent acting for the token's owner. MCP changes form one session that `undo_session` reverts.
- The OpenAPI document at https://developers.lydie.co/openapi.json is the source of truth for every field.

## Get started

- [Quickstart](https://developers.lydie.co/quickstart.md): Create an API token, find your workspace, and create, read and edit a document with the REST API.
- [Authentication](https://developers.lydie.co/authentication.md): Personal API tokens for scripts, OAuth 2.1 for apps and MCP clients, and what each kind of token may do.
- [MCP server](https://developers.lydie.co/mcp.md): Connect Claude, Cursor, VS Code or any MCP client to a Lydie workspace, hosted or on your own computer.
- [MCP tools](https://developers.lydie.co/mcp/tools.md): Every tool the hosted MCP server lists.

## Concepts

- [Documents and Markdown](https://developers.lydie.co/documents.md): How pages, bodies, properties, links and the trash work, and how to edit a body safely while people are typing in it.
- [Agent changes and undo](https://developers.lydie.co/agent-history.md): Lydie records which agent made each change and for whom, and can undo everything one agent session did in one step.
- [Errors and versions](https://developers.lydie.co/errors.md): The error envelope and its codes, warnings on partial success, and how the API is versioned.

## API reference

- [Introduction](https://developers.lydie.co/api.md): Base URL, conventions and resources
- [Documents](https://developers.lydie.co/api/documents.md): Pages in a workspace: a tree of documents, each with a title, typed properties (frontmatter) and a Markdown body.
  - [Create a document](https://developers.lydie.co/api/documents/create-a-document.md): `POST /v1/documents`
  - [Get a document](https://developers.lydie.co/api/documents/get-a-document.md): `GET /v1/documents/{id}`
  - [Delete a document](https://developers.lydie.co/api/documents/delete-a-document.md): `DELETE /v1/documents/{id}`
  - [List backlinks](https://developers.lydie.co/api/documents/list-backlinks.md): `GET /v1/documents/{id}/backlinks`
  - [List backlinks to a block](https://developers.lydie.co/api/documents/list-backlinks-to-a-block.md): `GET /v1/documents/{id}/blocks/{blockId}/backlinks`
  - [Update a document body](https://developers.lydie.co/api/documents/update-a-document-body.md): `PATCH /v1/documents/{id}/body`
  - [List outgoing links](https://developers.lydie.co/api/documents/list-outgoing-links.md): `GET /v1/documents/{id}/links`
  - [Move a document](https://developers.lydie.co/api/documents/move-a-document.md): `POST /v1/documents/{id}/move`
  - [Set document properties](https://developers.lydie.co/api/documents/set-document-properties.md): `PATCH /v1/documents/{id}/properties`
  - [Permanently delete a document](https://developers.lydie.co/api/documents/permanently-delete-a-document.md): `POST /v1/documents/{id}/purge`
  - [Rename a document](https://developers.lydie.co/api/documents/rename-a-document.md): `POST /v1/documents/{id}/rename`
  - [Restore a deleted document](https://developers.lydie.co/api/documents/restore-a-deleted-document.md): `POST /v1/documents/{id}/restore`
  - [Move a page to another teamspace or to Private](https://developers.lydie.co/api/documents/move-a-page-to-another-teamspace-or-to-private.md): `POST /v1/documents/{id}/space`
  - [List unlinked mentions](https://developers.lydie.co/api/documents/list-unlinked-mentions.md): `GET /v1/documents/{id}/unlinked-mentions`
  - [List a document's versions](https://developers.lydie.co/api/documents/list-a-documents-versions.md): `GET /v1/documents/{id}/versions`
  - [Get a document version](https://developers.lydie.co/api/documents/get-a-document-version.md): `GET /v1/documents/{id}/versions/{versionId}`
  - [Restore a document version](https://developers.lydie.co/api/documents/restore-a-document-version.md): `POST /v1/documents/{id}/versions/{versionId}/restore`
  - [List a document's children](https://developers.lydie.co/api/documents/list-a-documents-children.md): `GET /v1/workspaces/{workspaceId}/children`
  - [Search documents](https://developers.lydie.co/api/documents/search-documents.md): `GET /v1/workspaces/{workspaceId}/search`
  - [List the document tree](https://developers.lydie.co/api/documents/list-the-document-tree.md): `GET /v1/workspaces/{workspaceId}/tree`
  - [List unresolved links](https://developers.lydie.co/api/documents/list-unresolved-links.md): `GET /v1/workspaces/{workspaceId}/unresolved-links`
- [Databases](https://developers.lydie.co/api/databases.md): A database is a document whose children are its rows. Each row is a document; its values are the row's properties.
  - [Update a database property](https://developers.lydie.co/api/databases/update-a-database-property.md): `PATCH /v1/database-properties/{id}`
  - [Delete a database property](https://developers.lydie.co/api/databases/delete-a-database-property.md): `DELETE /v1/database-properties/{id}`
  - [Reorder a database property](https://developers.lydie.co/api/databases/reorder-a-database-property.md): `POST /v1/database-properties/{id}/move`
  - [Rename a database property](https://developers.lydie.co/api/databases/rename-a-database-property.md): `POST /v1/database-properties/{id}/rename`
  - [Restore a database property](https://developers.lydie.co/api/databases/restore-a-database-property.md): `POST /v1/database-properties/{id}/restore`
  - [Change a property's type](https://developers.lydie.co/api/databases/change-a-propertys-type.md): `POST /v1/database-properties/{id}/type`
  - [Add a select option](https://developers.lydie.co/api/databases/add-a-select-option.md): `POST /v1/database-properties/{propertyId}/options`
  - [Rename or recolour a select option](https://developers.lydie.co/api/databases/rename-or-recolour-a-select-option.md): `PATCH /v1/database-properties/{propertyId}/options/{optionId}`
  - [Delete a select option](https://developers.lydie.co/api/databases/delete-a-select-option.md): `DELETE /v1/database-properties/{propertyId}/options/{optionId}`
  - [Reorder a select option](https://developers.lydie.co/api/databases/reorder-a-select-option.md): `POST /v1/database-properties/{propertyId}/options/{optionId}/move`
  - [Move a database row](https://developers.lydie.co/api/databases/move-a-database-row.md): `POST /v1/database-rows/{rowId}/move`
  - [Update a database view](https://developers.lydie.co/api/databases/update-a-database-view.md): `PATCH /v1/database-views/{id}`
  - [Delete a database view](https://developers.lydie.co/api/databases/delete-a-database-view.md): `DELETE /v1/database-views/{id}`
  - [Duplicate a database view](https://developers.lydie.co/api/databases/duplicate-a-database-view.md): `POST /v1/database-views/{id}/duplicate`
  - [Reorder a database view](https://developers.lydie.co/api/databases/reorder-a-database-view.md): `POST /v1/database-views/{id}/move`
  - [Rename a database view](https://developers.lydie.co/api/databases/rename-a-database-view.md): `POST /v1/database-views/{id}/rename`
  - [Restore a database view](https://developers.lydie.co/api/databases/restore-a-database-view.md): `POST /v1/database-views/{id}/restore`
  - [Create a database](https://developers.lydie.co/api/databases/create-a-database.md): `POST /v1/databases`
  - [Add a database property](https://developers.lydie.co/api/databases/add-a-database-property.md): `POST /v1/databases/{databaseId}/properties`
  - [Query a database](https://developers.lydie.co/api/databases/query-a-database.md): `POST /v1/databases/{databaseId}/query`
  - [Create a database row](https://developers.lydie.co/api/databases/create-a-database-row.md): `POST /v1/databases/{databaseId}/rows`
  - [Set row values](https://developers.lydie.co/api/databases/set-row-values.md): `PATCH /v1/databases/{databaseId}/rows`
  - [Delete database rows](https://developers.lydie.co/api/databases/delete-database-rows.md): `POST /v1/databases/{databaseId}/rows/delete`
  - [Duplicate database rows](https://developers.lydie.co/api/databases/duplicate-database-rows.md): `POST /v1/databases/{databaseId}/rows/duplicate`
  - [Restore database rows](https://developers.lydie.co/api/databases/restore-database-rows.md): `POST /v1/databases/{databaseId}/rows/restore`
  - [Write database rows](https://developers.lydie.co/api/databases/write-database-rows.md): `POST /v1/databases/{databaseId}/rows/write`
  - [Change a database's properties](https://developers.lydie.co/api/databases/change-a-databases-properties.md): `POST /v1/databases/{databaseId}/schema`
  - [List row templates](https://developers.lydie.co/api/databases/list-row-templates.md): `GET /v1/databases/{databaseId}/templates`
  - [Create a database view](https://developers.lydie.co/api/databases/create-a-database-view.md): `POST /v1/databases/{databaseId}/views`
  - [Change a database's views](https://developers.lydie.co/api/databases/change-a-databases-views.md): `POST /v1/databases/{databaseId}/views/change`
  - [Get a database](https://developers.lydie.co/api/databases/get-a-database.md): `GET /v1/databases/{id}`
  - [Update database settings](https://developers.lydie.co/api/databases/update-database-settings.md): `PATCH /v1/databases/{id}`
  - [Turn a database back into a page](https://developers.lydie.co/api/databases/turn-a-database-back-into-a-page.md): `DELETE /v1/databases/{id}`
  - [Replace a database's schema and views](https://developers.lydie.co/api/databases/replace-a-databases-schema-and-views.md): `PUT /v1/databases/{id}/definition`
  - [Restore a database](https://developers.lydie.co/api/databases/restore-a-database.md): `POST /v1/databases/{id}/restore`
  - [List databases](https://developers.lydie.co/api/databases/list-databases.md): `GET /v1/workspaces/{workspaceId}/databases`
- [Attachments](https://developers.lydie.co/api/attachments.md): Files attached to a workspace or a document, stored by their SHA-256 hash. Upload the bytes first, then record the attachment.
  - [Add an attachment](https://developers.lydie.co/api/attachments/add-an-attachment.md): `POST /v1/attachments`
  - [Get an upload URL for a file](https://developers.lydie.co/api/attachments/get-an-upload-url-for-a-file.md): `POST /v1/attachments/uploads`
  - [Get an attachment](https://developers.lydie.co/api/attachments/get-an-attachment.md): `GET /v1/attachments/{id}`
  - [Delete an attachment](https://developers.lydie.co/api/attachments/delete-an-attachment.md): `DELETE /v1/attachments/{id}`
  - [Get a download URL for an attachment](https://developers.lydie.co/api/attachments/get-a-download-url-for-an-attachment.md): `GET /v1/attachments/{id}/download-url`
  - [Permanently delete an attachment](https://developers.lydie.co/api/attachments/permanently-delete-an-attachment.md): `POST /v1/attachments/{id}/purge`
  - [Restore an attachment](https://developers.lydie.co/api/attachments/restore-an-attachment.md): `POST /v1/attachments/{id}/restore`
  - [List attachments](https://developers.lydie.co/api/attachments/list-attachments.md): `GET /v1/workspaces/{workspaceId}/attachments`
- [Trash](https://developers.lydie.co/api/trash.md): Deleted documents and attachments stay in the trash until they are restored or purged.
  - [List the trash](https://developers.lydie.co/api/trash/list-the-trash.md): `GET /v1/workspaces/{workspaceId}/trash`
  - [Empty the trash](https://developers.lydie.co/api/trash/empty-the-trash.md): `DELETE /v1/workspaces/{workspaceId}/trash`
- [History](https://developers.lydie.co/api/history.md): Sessions group the changes an agent made, so they can be reviewed and undone together.
  - [List agent sessions](https://developers.lydie.co/api/history/list-agent-sessions.md): `GET /v1/history/sessions`
  - [List a session's changes](https://developers.lydie.co/api/history/list-a-sessions-changes.md): `GET /v1/history/sessions/{sessionId}`
  - [Undo a session](https://developers.lydie.co/api/history/undo-a-session.md): `POST /v1/history/sessions/{sessionId}/undo`
- [Workspaces](https://developers.lydie.co/api/workspaces.md): A workspace holds documents, members and teamspaces. An API token belongs to exactly one.
  - [List your workspaces](https://developers.lydie.co/api/workspaces/list-your-workspaces.md): `GET /v1/workspaces`
  - [Create a workspace](https://developers.lydie.co/api/workspaces/create-a-workspace.md): `POST /v1/workspaces`
  - [Rename a workspace](https://developers.lydie.co/api/workspaces/rename-a-workspace.md): `PATCH /v1/workspaces/{workspaceId}`
  - [Transfer workspace ownership](https://developers.lydie.co/api/workspaces/transfer-workspace-ownership.md): `POST /v1/workspaces/{workspaceId}/transfer-ownership`
- [Members](https://developers.lydie.co/api/members.md): People in a workspace and their roles: owner, admin, member or guest.
  - [Leave a workspace](https://developers.lydie.co/api/members/leave-a-workspace.md): `POST /v1/workspaces/{workspaceId}/leave`
  - [List workspace members](https://developers.lydie.co/api/members/list-workspace-members.md): `GET /v1/workspaces/{workspaceId}/members`
  - [Remove a member](https://developers.lydie.co/api/members/remove-a-member.md): `DELETE /v1/workspaces/{workspaceId}/members/{userId}`
  - [Change a member's role](https://developers.lydie.co/api/members/change-a-members-role.md): `POST /v1/workspaces/{workspaceId}/members/{userId}/role`
- [Teamspaces](https://developers.lydie.co/api/teamspaces.md): Groups of pages with their own members. Open teamspaces are visible to every member; closed and private ones are not.
  - [Update a teamspace](https://developers.lydie.co/api/teamspaces/update-a-teamspace.md): `PATCH /v1/teamspaces/{teamspaceId}`
  - [Delete a teamspace](https://developers.lydie.co/api/teamspaces/delete-a-teamspace.md): `DELETE /v1/teamspaces/{teamspaceId}`
  - [Join an open teamspace](https://developers.lydie.co/api/teamspaces/join-an-open-teamspace.md): `POST /v1/teamspaces/{teamspaceId}/join`
  - [Leave a teamspace](https://developers.lydie.co/api/teamspaces/leave-a-teamspace.md): `POST /v1/teamspaces/{teamspaceId}/leave`
  - [List teamspace members](https://developers.lydie.co/api/teamspaces/list-teamspace-members.md): `GET /v1/teamspaces/{teamspaceId}/members`
  - [Add someone to a teamspace](https://developers.lydie.co/api/teamspaces/add-someone-to-a-teamspace.md): `POST /v1/teamspaces/{teamspaceId}/members`
  - [Remove someone from a teamspace](https://developers.lydie.co/api/teamspaces/remove-someone-from-a-teamspace.md): `DELETE /v1/teamspaces/{teamspaceId}/members/{userId}`
  - [Change a teamspace member's role](https://developers.lydie.co/api/teamspaces/change-a-teamspace-members-role.md): `POST /v1/teamspaces/{teamspaceId}/members/{userId}/role`
  - [Restore a deleted teamspace](https://developers.lydie.co/api/teamspaces/restore-a-deleted-teamspace.md): `POST /v1/teamspaces/{teamspaceId}/restore`
  - [List teamspaces](https://developers.lydie.co/api/teamspaces/list-teamspaces.md): `GET /v1/workspaces/{workspaceId}/teamspaces`
  - [Create a teamspace](https://developers.lydie.co/api/teamspaces/create-a-teamspace.md): `POST /v1/workspaces/{workspaceId}/teamspaces`
- [Invitations](https://developers.lydie.co/api/invitations.md): Email invitations to join a workspace.
  - [Accept an invitation](https://developers.lydie.co/api/invitations/accept-an-invitation.md): `POST /v1/invitations/accept`
  - [Decline an invitation](https://developers.lydie.co/api/invitations/decline-an-invitation.md): `POST /v1/invitations/decline`
  - [Look up an invitation by its token](https://developers.lydie.co/api/invitations/look-up-an-invitation-by-its-token.md): `GET /v1/invitations/lookup`
  - [Revoke an invitation](https://developers.lydie.co/api/invitations/revoke-an-invitation.md): `DELETE /v1/invitations/{invitationId}`
  - [Resend an invitation](https://developers.lydie.co/api/invitations/resend-an-invitation.md): `POST /v1/invitations/{invitationId}/resend`
  - [List pending invitations](https://developers.lydie.co/api/invitations/list-pending-invitations.md): `GET /v1/workspaces/{workspaceId}/invitations`
  - [Invite someone by email](https://developers.lydie.co/api/invitations/invite-someone-by-email.md): `POST /v1/workspaces/{workspaceId}/invitations`
- [Sharing](https://developers.lydie.co/api/sharing.md): Who can see a page: grants to people, teamspaces or the whole workspace, restricted pages, and public links.
  - [Share a page](https://developers.lydie.co/api/sharing/share-a-page.md): `POST /v1/documents/{documentId}/grants`
  - [Stop sharing a page](https://developers.lydie.co/api/sharing/stop-sharing-a-page.md): `DELETE /v1/documents/{documentId}/grants/{grantId}`
  - [Share a page with someone by email](https://developers.lydie.co/api/sharing/share-a-page-with-someone-by-email.md): `POST /v1/documents/{documentId}/invite`
  - [Restrict or unrestrict a page](https://developers.lydie.co/api/sharing/restrict-or-unrestrict-a-page.md): `POST /v1/documents/{documentId}/restricted`
  - [List a page's public links](https://developers.lydie.co/api/sharing/list-a-pages-public-links.md): `GET /v1/documents/{documentId}/share-links`
  - [Create a public link](https://developers.lydie.co/api/sharing/create-a-public-link.md): `POST /v1/documents/{documentId}/share-links`
  - [Get a page's sharing settings](https://developers.lydie.co/api/sharing/get-a-pages-sharing-settings.md): `GET /v1/documents/{documentId}/sharing`
  - [Change a public link](https://developers.lydie.co/api/sharing/change-a-public-link.md): `PATCH /v1/share-links/{shareLinkId}`
  - [Revoke a public link](https://developers.lydie.co/api/sharing/revoke-a-public-link.md): `DELETE /v1/share-links/{shareLinkId}`
- [Notifications](https://developers.lydie.co/api/notifications.md): Your inbox: mentions, shares and accepted invitations.
  - [List notifications](https://developers.lydie.co/api/notifications/list-notifications.md): `GET /v1/notifications`
  - [Archive notifications](https://developers.lydie.co/api/notifications/archive-notifications.md): `POST /v1/notifications/archive`
  - [Get notification preferences](https://developers.lydie.co/api/notifications/get-notification-preferences.md): `GET /v1/notifications/preferences`
  - [Set notification preferences](https://developers.lydie.co/api/notifications/set-notification-preferences.md): `PUT /v1/notifications/preferences`
  - [Mark notifications read](https://developers.lydie.co/api/notifications/mark-notifications-read.md): `POST /v1/notifications/read`
  - [Mark all notifications read](https://developers.lydie.co/api/notifications/mark-all-notifications-read.md): `POST /v1/notifications/read-all`
- [Publishing](https://developers.lydie.co/api/publishing.md): Publish documents to GitHub, WordPress or a webhook. A connection holds the credentials; a publication says what goes where.
  - [Get a connection](https://developers.lydie.co/api/publishing/get-a-connection.md): `GET /v1/connections/{id}`
  - [Change a connection](https://developers.lydie.co/api/publishing/change-a-connection.md): `PATCH /v1/connections/{id}`
  - [Remove a connection](https://developers.lydie.co/api/publishing/remove-a-connection.md): `DELETE /v1/connections/{id}`
  - [Test a connection](https://developers.lydie.co/api/publishing/test-a-connection.md): `POST /v1/connections/{id}/test`
  - [List publishing connectors](https://developers.lydie.co/api/publishing/list-publishing-connectors.md): `GET /v1/connectors`
  - [Publish a document to a connection](https://developers.lydie.co/api/publishing/publish-a-document-to-a-connection.md): `POST /v1/documents/{documentId}/publications`
  - [Get a publication](https://developers.lydie.co/api/publishing/get-a-publication.md): `GET /v1/publications/{id}`
  - [Change a publication](https://developers.lydie.co/api/publishing/change-a-publication.md): `PATCH /v1/publications/{id}`
  - [Remove a publication](https://developers.lydie.co/api/publishing/remove-a-publication.md): `DELETE /v1/publications/{id}`
  - [Resolve a diverged document](https://developers.lydie.co/api/publishing/resolve-a-diverged-document.md): `POST /v1/publications/{id}/resolve`
  - [Publish now](https://developers.lydie.co/api/publishing/publish-now.md): `POST /v1/publications/{id}/run`
  - [List a publication's runs](https://developers.lydie.co/api/publishing/list-a-publications-runs.md): `GET /v1/publications/{id}/runs`
  - [Unpublish](https://developers.lydie.co/api/publishing/unpublish.md): `POST /v1/publications/{id}/unpublish`
  - [List connections](https://developers.lydie.co/api/publishing/list-connections.md): `GET /v1/workspaces/{workspaceId}/connections`
  - [Connect a destination](https://developers.lydie.co/api/publishing/connect-a-destination.md): `POST /v1/workspaces/{workspaceId}/connections`
  - [Start connecting with OAuth](https://developers.lydie.co/api/publishing/start-connecting-with-oauth.md): `POST /v1/workspaces/{workspaceId}/connections/authorize`
  - [List publications](https://developers.lydie.co/api/publishing/list-publications.md): `GET /v1/workspaces/{workspaceId}/publications`
- [API tokens](https://developers.lydie.co/api/api-tokens.md): Personal API tokens. These endpoints need a signed-in session: a token cannot create or list tokens.
  - [Revoke an API token](https://developers.lydie.co/api/api-tokens/revoke-an-api-token.md): `DELETE /v1/api-tokens/{tokenId}`
  - [List your API tokens](https://developers.lydie.co/api/api-tokens/list-your-api-tokens.md): `GET /v1/workspaces/{workspaceId}/api-tokens`
  - [Create an API token](https://developers.lydie.co/api/api-tokens/create-an-api-token.md): `POST /v1/workspaces/{workspaceId}/api-tokens`
- [Connected apps](https://developers.lydie.co/api/connected-apps.md): Apps you allowed through OAuth, such as MCP clients. Signed-in session only.
  - [Disconnect an app](https://developers.lydie.co/api/connected-apps/disconnect-an-app.md): `DELETE /v1/oauth-grants/{grantId}`
  - [List connected apps](https://developers.lydie.co/api/connected-apps/list-connected-apps.md): `GET /v1/workspaces/{workspaceId}/oauth-grants`

## Specs

- [OpenAPI 3.1 document](https://developers.lydie.co/openapi.json): Every endpoint, parameter and schema

## Optional

- [Every page in one file](https://developers.lydie.co/llms-full.txt): All guides and endpoints as one Markdown file