Search API

Search your knowledge base using semantic (AI-powered) search.

Endpoints

Method	Path	Description
POST	/workspaces/:id/search	Search documents
GET	/s/:linkId	Public search via search link

Search documents

POST /workspaces/:id/search

Perform semantic search across all documents in a workspace.

Request

{
  "query": "What is the refund policy?",
  "limit": 5,
  "filters": {
    "tags": ["tag_abc"],
    "purpose": "KNOWLEDGE"
  }
}

Parameters

Field	Type	Required	Description
query	String	Yes	Natural language question
limit	Number	No	Max results (default: 5, max: 20)
filters.tags	String[]	No	Filter by tag IDs
filters.purpose	String	No	Filter by purpose
filters.documentIds	String[]	No	Limit to specific docs

Response

{
  "query": "What is the refund policy?",
  "results": [
    {
      "documentId": "doc_xyz789",
      "documentTitle": "Terms of Service",
      "content": "Our refund policy allows customers to request a full refund within 14 days of purchase...",
      "score": 0.95,
      "chunkIndex": 3,
      "metadata": {
        "page": 5,
        "section": "Refunds"
      }
    },
    {
      "documentId": "doc_abc123",
      "documentTitle": "FAQ",
      "content": "Q: Can I get a refund? A: Yes, we offer a 14-day money-back guarantee...",
      "score": 0.88,
      "chunkIndex": 12
    }
  ],
  "processingTime": 245
}

Example

cURL

curl -X POST "https://api.synjar.com/v1/workspaces/ws_abc123/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund policy?",
    "limit": 5
  }'

JavaScript

const response = await fetch(
  'https://api.synjar.com/v1/workspaces/ws_abc123/search',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'What is the refund policy?',
      limit: 5,
    }),
  }
);

const { results } = await response.json();
console.log(results[0].content);

Python

response = requests.post(
    'https://api.synjar.com/v1/workspaces/ws_abc123/search',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'query': 'What is the refund policy?',
        'limit': 5
    }
)

results = response.json()['results']
print(results[0]['content'])

Public search (search links)

GET /s/:linkId

Search via public search link. No authentication required.

Query parameters

Parameter	Type	Description
q	String	Search query
limit	Number	Max results (default: 3)

Example

curl "https://api.synjar.com/s/sl_abc123?q=refund%20policy&limit=3"

See Search links API for details.

How semantic search works

Synjar uses RAG (Retrieval-Augmented Generation):

1. Query embedding: Your question is converted to a vector
2. Vector search: Similar document chunks are retrieved
3. Ranking: Results are ranked by semantic similarity
4. Response: Top-N most relevant chunks are returned

Similarity score

The score field (0-1) indicates semantic similarity:

Score	Meaning
0.9+	Very high relevance
0.7-0.9	Good relevance
0.5-0.7	Moderate relevance
<0.5	Low relevance

Search tips

Be specific

// Good
{ "query": "What is the return window for electronics?" }

// Too vague
{ "query": "returns" }

Ask questions

Natural language questions work better than keywords:

// Better
{ "query": "How do I cancel my subscription?" }

// Less effective
{ "query": "cancel subscription" }

Use filters

Narrow results with filters:

{
  "query": "pricing",
  "filters": {
    "tags": ["tag_sales"],
    "documentIds": ["doc_terms", "doc_pricing"]
  }
}

Rate limits

Endpoint	Limit
Workspace search	60/minute
Public search links	30/minute

See Rate limits for details.

Error responses

Status	Code	Description
400	QUERY_REQUIRED	Missing query parameter
400	QUERY_TOO_LONG	Query exceeds 1000 characters
401	UNAUTHORIZED	Missing or invalid token
404	WORKSPACE_NOT_FOUND	Workspace doesn't exist
429	RATE_LIMITED	Too many requests

See also

• Search links API
• Instruction sets API
• Asking questions
• Advanced search tips