API Reference

Documents

List and retrieve documents from your Notery workspace.

List Documents

GET/api/v1/documents

Retrieve a paginated list of documents in your workspace. Results are ordered by path and title.

Parameters

Parameter	Type	Required	Default	Description
`folder`	string	No	--	Filter to documents whose path starts with this prefix (e.g. `/guides`).
`tags`	string	No	--	Comma-separated list of tags to filter by. Only documents that have at least one matching tag are returned.
`limit`	number	No	`50`	Maximum number of documents to return. Capped at `100`.
`offset`	number	No	`0`	Number of documents to skip, for pagination.

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Authentication Architecture",
      "path": "/projects/backend/auth.md",
      "slug": "auth",
      "tags": ["auth", "backend"],
      "fileType": "markdown",
      "wordCount": 1240,
      "summary": "Overview of the BetterAuth-based authentication system.",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "modifiedAt": "2026-02-10T14:22:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Unique document ID (UUID).
`title`	string	Document title.
`path`	string	Full path of the document within the workspace.
`slug`	string	URL-friendly slug derived from the document title.
`tags`	string	Array of tags assigned to the document.
`fileType`	string	File type (`markdown` or `code`).
`wordCount`	number \| null	Word count of the document content.
`summary`	string \| null	AI-generated summary of the document, if available.
`createdAt`	string	ISO 8601 timestamp of when the document was created.
`modifiedAt`	string	ISO 8601 timestamp of when the document was last modified.

The list endpoint does not return the full document content. Use the Get Document endpoint to retrieve the complete markdown body.

Pagination

Use limit and offset to paginate through large workspaces:

# First page (documents 1-50)
curl -s "https://notery.dev/api/v1/documents?limit=50&offset=0" \
  -H "Authorization: Bearer ntry_abc123def456..."

# Second page (documents 51-100)
curl -s "https://notery.dev/api/v1/documents?limit=50&offset=50" \
  -H "Authorization: Bearer ntry_abc123def456..."

Examples

curl

curl -s "https://notery.dev/api/v1/documents?limit=20" \
  -H "Authorization: Bearer ntry_abc123def456..."

Filtering by folder

curl -s "https://notery.dev/api/v1/documents?folder=/projects/backend" \
  -H "Authorization: Bearer ntry_abc123def456..."

Filtering by tags

curl -s "https://notery.dev/api/v1/documents?tags=auth,security" \
  -H "Authorization: Bearer ntry_abc123def456..."

Get Document

GET/api/v1/documents/:id

Retrieve a single document by its ID, including the full markdown content.

Parameters

Parameter	Location	Type	Required	Description
`id`	URL path	string	Yes	The document's UUID.

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Authentication Architecture",
    "path": "/projects/backend/auth.md",
    "slug": "auth",
    "tags": ["auth", "backend"],
    "content": "# Authentication Architecture\n\nThis document describes...",
    "metadata": {},
    "contentPlain": "Authentication Architecture. This document describes...",
    "wordCount": 1240,
    "fileType": "markdown",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "modifiedAt": "2026-02-10T14:22:00.000Z"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique document ID (UUID).
`title`	string	Document title.
`path`	string	Full path of the document within the workspace.
`slug`	string	URL-friendly slug derived from the document title.
`tags`	string	Array of tags assigned to the document.
`content`	string	Full markdown content of the document.
`metadata`	object	Arbitrary metadata associated with the document (e.g. frontmatter fields).
`contentPlain`	string \| null	Plain-text version of the content with markdown stripped.
`wordCount`	number \| null	Word count of the document content.
`fileType`	string	File type (`markdown` or `code`).
`createdAt`	string	ISO 8601 timestamp of when the document was created.
`modifiedAt`	string	ISO 8601 timestamp of when the document was last modified.

This is the only endpoint that returns the full content field. Use it when you need to read the actual document body. The list endpoint omits content to keep responses lightweight.

Errors

Status	Cause
`400`	Missing document ID in the URL path.
`401`	Missing or invalid API key.
`404`	Document not found, or it belongs to a different workspace, or it has been deleted.

Examples

curl

curl -s "https://notery.dev/api/v1/documents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ntry_abc123def456..."

JavaScript (fetch)

const docId = '550e8400-e29b-41d4-a716-446655440000'

const response = await fetch(
  `https://notery.dev/api/v1/documents/${docId}`,
  {
    headers: {
      'Authorization': 'Bearer ntry_abc123def456...'
    }
  }
)

const { data } = await response.json()

console.log(data.title)
console.log(data.content)