Search Documents
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.
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 |
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 |