API Reference

Search

Search your documents using semantic similarity with the Notery API.

Search Documents

GET/api/v1/search

Search your workspace documents using semantic similarity. Queries are embedded using Cohere embed-v4 and matched against document embeddings stored in pgvector.

Embeddings are generated automatically when documents are saved. Only documents with embeddings will appear in search results.

Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	--	The search query. Must be a non-empty string.
`limit`	number	No	`20`	Maximum number of results to return. Capped at `50`.
`folder`	string	No	--	Filter results to documents whose path starts with this prefix (e.g. `/projects/backend`).
`tags`	string	No	--	Comma-separated list of tags to filter by. Only documents that have at least one matching tag are returned.

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "/projects/backend/auth.md",
      "slug": "auth",
      "title": "Authentication Architecture",
      "tags": ["auth", "backend"],
      "fileType": "markdown",
      "contentPlain": "This document describes the authentication...",
      "summary": "Overview of the BetterAuth-based authentication system.",
      "similarity": 0.87
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Unique document ID (UUID).
`path`	string	Full path of the document within the workspace.
`slug`	string	URL-friendly slug derived from the document title.
`title`	string	Document title.
`tags`	string	Array of tags assigned to the document.
`fileType`	string	File type (`markdown` or `code`).
`contentPlain`	string	Plain-text content of the document (markdown stripped).
`summary`	string \| null	AI-generated summary of the document, if available.
`similarity`	number	Cosine similarity score between the query and the document embedding. Higher values indicate a closer match (range 0 to 1).

Pro and Team workspaces automatically benefit from Cohere reranking. The API fetches a broader set of initial vector matches and then reranks them for more accurate ordering. No changes to your request are needed -- reranking is applied transparently based on your workspace plan.

Errors

Status	Cause
`400`	Missing or empty `q` parameter.
`401`	Missing or invalid API key.
`403`	Search disabled -- free-plan workspace exceeds its document limit. Upgrade to Pro to re-enable search.

Examples

curl

curl -s "https://notery.dev/api/v1/search?q=authentication+flow&limit=5" \
  -H "Authorization: Bearer ntry_abc123def456..."

JavaScript (fetch)

const response = await fetch(
  'https://notery.dev/api/v1/search?' + new URLSearchParams({
    q: 'authentication flow',
    limit: '5',
    tags: 'backend,auth'
  }),
  {
    headers: {
      'Authorization': 'Bearer ntry_abc123def456...'
    }
  }
)

const { data } = await response.json()

for (const doc of data) {
  console.log(`${doc.title} (${doc.similarity.toFixed(2)})`)
}

Filtering by folder

curl -s "https://notery.dev/api/v1/search?q=database+schema&folder=/projects/backend" \
  -H "Authorization: Bearer ntry_abc123def456..."

Filtering by tags

curl -s "https://notery.dev/api/v1/search?q=deployment&tags=devops,infrastructure" \
  -H "Authorization: Bearer ntry_abc123def456..."