Search Documents

Search documents by title prefix and/or tag

Search Documents

GET /v1/documents/search

Search documents by title prefix and/or tag. At least one of q or tag is required. Results are scoped to the authenticated user.

Query Parameters

Parameter	Type	Required	Description
q	string	No*	Title prefix to search for (case-insensitive)
tag	string	No*	Exact tag to match from metadata.tags
folder_id	string	No	Scope results to a specific folder
limit	integer	No	Max results (default: 20, max: 50)
offset	integer	No	Number of results to skip

At least one of q or tag is required.

Required role: documents:read

Example Request

curl "https://api.surfacedocs.dev/v1/documents/search?q=API&tag=guide&limit=10" \
  -H "X-API-Key: sd_live_..."

Response

{
  "results": [
    {
      "id": "doc_abc123",
      "url": "https://app.surfacedocs.dev/d/doc_abc123",
      "folder_id": "fld_xyz",
      "title": "API Documentation",
      "content_type": "markdown",
      "block_count": 15,
      "metadata": {
        "tags": ["api", "guide"],
        "source": "claude-3"
      },
      "visibility": "private",
      "current_version": 3,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z"
    }
  ],
  "count": 1,
  "query": "API",
  "tag": "guide",
  "folder_id": null
}

Response Fields

Field	Type	Description
results	array	List of matching documents
count	integer	Number of results returned
query	string | null	The title query used
tag	string | null	The tag filter used
folder_id	string | null	The folder scope used

Each result in results contains:

Field	Type	Description
id	string	Document ID
url	string	URL to view the document
folder_id	string	Parent folder ID
title	string	Document title
content_type	string	Content type (markdown, html, text)
block_count	integer	Number of content blocks
metadata	object | null	Document metadata including tags
visibility	string	Document visibility
current_version	integer | null	Current version number
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Search Behavior

• Title search (q): Case-insensitive prefix match. Searching q=api matches “API Documentation”, “api-guide”, etc.
• Tag search (tag): Exact match against the metadata.tags array.
• Combined: When both q and tag are provided, results must match both (AND logic).
• Folder scope: When folder_id is provided, only documents in that folder are searched.

Errors

Code	Description
422	Neither q nor tag provided
401	Invalid or missing API key
403	API key lacks documents:read role
404	Specified folder_id not found