Spaces API – POST /api/spaces/{space}/search

🔍 Search documents within a specific Space by keyword. Returns paginated, highlighted snippets and metadata.

Authentication

All endpoints under /api require a Bearer token

  • Header: - Authorization: Bearer

Endpoint

{
    "title": "Search Space Documents",
    "description": "Search documents within a specific space",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/spaces/{space}/search",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "space",
            "value": "Space ID or slug",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n  \"query\": \"search terms\",\n  \"page\": 1,\n  \"per_page\": 20,\n  \"highlight\": true\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Successful search response",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"results\": [\n      {\n        \"id\": 123,\n        \"item_type\": \"page\",\n        \"title\": \"API Documentation\",\n        \"url\": \"https://docuwriter.ai/spaces/project-space/documents/123\",\n        \"snippet\": \"Auto-generated API docs...\",\n        \"score\": 0.95,\n        \"updated_at\": \"2025-09-01T12:34:56Z\"\n      }\n    ],\n    \"pagination\": {\n      \"current_page\": 1,\n      \"last_page\": 5,\n      \"per_page\": 20,\n      \"total\": 100\n    },\n    \"query\": \"API\",\n    \"space\": { \"id\": 1, \"name\": \"Project Space\", \"is_public\": true }\n  }\n}"
        },
        "403": {
            "description": "Forbidden: no access to this space",
            "body": "{\n  \"success\": false,\n  \"message\": \"Access denied. You do not have permission to search this space.\"\n}"
        },
        "422": {
            "description": "Validation error",
            "body": "{\n  \"message\": \"The given data was invalid.\",\n  \"errors\": {\n    \"query\": [\"The query field is required.\"]\n  }\n}"
        },
        "500": {
            "description": "Server error during search",
            "body": "{\n  \"success\": false,\n  \"message\": \"An error occurred while searching. Please try again.\"\n}"
        }
    }
}

Request Parameters

Single JSON payload controls search behavior.

Parameter Type Required Default Description
query string Yes — Search keyword(s), min 2 chars
page integer No 1 Page number, ≥ 1
per_page integer No 20 Items per page, 1–100
highlight boolean No true Wrap matched terms in <mark></mark> tags

Query Syntax

  • Free-text search only; no special operators.
  • Terms shorter than 2 characters are ignored by validation.

Success Response (200)

Returns a list of matched SpaceMenuItem objects with pagination.

Body Schema

Field Type Description
success boolean Always true
data.results array List of search hits
data.pagination object Paging info (currentpage, last``page, per_page, total)
data.query string Echoes the sanitized query
data.space object Space metadata (id, name, is_public)

Result Item Shape

Field Type Description
id integer Unique identifier of the document
item_type string Enum: page, generation, etc.
title string Document name
url string Full URL to view the document
snippet string Truncated, highlighted content excerpt
score float Relevance score (default 1.0 if unset)
updated_at string ISO timestamp of last update