Documentation Search API

Search your workspace documentation using full-text search with multi-tenant isolation and locale preference.

Important: This endpoint is not part of the Public API. It requires JWT authentication (user session), not API keys. It's intended for use within the Agoralia web application.

Overview

The Documentation Search API allows you to search through:

Global documentation (available to all tenants)
Tenant-specific documentation (scoped to your workspace)

Results are ranked by relevance and can be filtered by language preference.

Authentication

This endpoint requires JWT authentication via the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Note: This is different from the Public API, which uses API keys. This endpoint is designed for internal use within the Agoralia application.

Endpoint

GET /docs/search

Base URL: https://api.agoralia.app

Full URL: https://api.agoralia.app/docs/search

Authentication: Required (JWT token with viewer role or higher)

Query Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	-	Search query (minimum 2 characters)
`locale`	string	No	`"en-US"`	Preferred language (BCP-47 format)

Example Request

curl -X GET "https://api.agoralia.app/docs/search?q=API%20keys&locale=en-US" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Note: Replace YOUR_JWT_TOKEN with a valid JWT token from your Agoralia session.

Response Format

{
  "results": [
    {
      "title": "API Keys Guide",
      "slug": "api-keys-guide",
      "url": "/docs/api-keys-guide",
      "snippet": "How to create API keys. API keys allow programmatic access...",
      "language": "en-US",
      "score": 0.85
    },
    {
      "title": "Guida alle API Keys",
      "slug": "api-keys-guide-it",
      "url": "/docs/api-keys-guide-it",
      "snippet": "Come creare API keys. Le API keys permettono accesso programmatico...",
      "language": "it-IT",
      "score": 0.78
    }
  ],
  "query": "API keys",
  "locale": "en-US"
}

Response Fields

Field	Type	Description
`results`	array	Array of documentation results
`results[].title`	string	Page title
`results[].slug`	string	URL slug
`results[].url`	string	Full URL path
`results[].snippet`	string	Text snippet (first 200 characters)
`results[].language`	string	Language code (BCP-47 format)
`results[].score`	number	Relevance score (0.0-1.0, higher is better)
`query`	string	Original search query
`locale`	string	Locale used for search

Language Preference

The API prefers results in the requested locale, but will include results in other languages if no matches are found.

Behavior:

Request with locale=it-IT will prefer Italian results
If few Italian results are found, English results will be included
Results are ordered by language match, then by relevance score

Example:

# Request Italian results
curl -X GET "https://api.agoralia.app/docs/search?q=API&locale=it-IT" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Response may include:
# 1. Italian results (if available)
# 2. English results (as fallback)

Multi-Tenant Support

The search respects tenant isolation:

Global docs (tenant_id=null): Available to all tenants
Tenant docs: Only visible to the tenant that created them

When searching, you'll see:

Your tenant-specific documentation (if any)
Global documentation (shared across all tenants)

Example:

Tenant A creates a custom doc → Only Tenant A can see it
Global doc is created → All tenants can see it
Tenant A searches → Sees both Tenant A docs and global docs
Tenant B searches → Sees only global docs (not Tenant A's docs)

Use Cases

1. Integration with Copilot

The Agoralia copilot uses this endpoint to provide contextual help:

User: "How do I create an API key?"
Copilot: [Searches docs] → Shows relevant documentation

2. Help System

Use in your help/FAQ pages to provide search functionality within the Agoralia application.

3. Contextual Documentation

Show relevant docs based on the current page or user action within the web interface.

Error Responses

401 Unauthorized

Cause: Missing or invalid JWT token.

Response:

{
  "detail": "Tenant ID required"
}

Solution: Ensure you're authenticated with a valid JWT token.

422 Validation Error

Cause: Query parameter validation failed.

Response:

{
  "detail": [
    {
      "loc": ["query", "q"],
      "msg": "ensure this value has at least 2 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

Solutions:

Ensure query (q) parameter is at least 2 characters
Check query parameter is properly URL-encoded

Example:

# ❌ Bad: Query too short
curl -X GET "https://api.agoralia.app/docs/search?q=A" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# ✅ Good: Query is at least 2 characters
curl -X GET "https://api.agoralia.app/docs/search?q=API" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Best Practices

✅ Use Specific Queries

More specific queries yield better results:

# ✅ Good: Specific query
q=API%20keys%20create

# ❌ Bad: Too generic
q=keys

✅ Set Locale

Always include locale parameter for better results:

# ✅ Good: Includes locale
?q=API&locale=it-IT

# ❌ Bad: No locale (defaults to en-US)
?q=API

✅ Handle Empty Results

Show helpful message when no docs found:

response = requests.get(url, headers=headers, params={"q": query})
data = response.json()

if not data["results"]:
    print(f"No documentation found for '{query}'")
else:
    for result in data["results"]:
        print(f"- {result['title']}: {result['url']}")

✅ Cache Results

Cache search results for common queries to reduce API calls:

from functools import lru_cache
import time

@lru_cache(maxsize=100)
def search_docs(query: str, locale: str = "en-US", cache_time: int = 300):
    """Search docs with caching"""
    # Cache for 5 minutes
    return requests.get(
        "https://api.agoralia.app/docs/search",
        headers={"Authorization": f"Bearer {token}"},
        params={"q": query, "locale": locale}
    ).json()

Implementation Example

Python

import requests

def search_documentation(query: str, locale: str = "en-US", jwt_token: str = None):
    """Search documentation"""
    if not jwt_token:
        raise ValueError("JWT token required")
    
    url = "https://api.agoralia.app/docs/search"
    headers = {
        "Authorization": f"Bearer {jwt_token}",
        "Content-Type": "application/json"
    }
    params = {
        "q": query,
        "locale": locale
    }
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            raise ValueError("Authentication failed - invalid JWT token")
        elif e.response.status_code == 422:
            error_data = e.response.json()
            raise ValueError(f"Validation error: {error_data.get('detail')}")
        raise

# Usage
results = search_documentation("API keys", locale="en-US", jwt_token="your-jwt-token")
for result in results["results"]:
    print(f"{result['title']}: {result['url']} (score: {result['score']:.2f})")

JavaScript/TypeScript

async function searchDocumentation(
  query: string,
  locale: string = "en-US",
  jwtToken: string
): Promise<DocsSearchResponse> {
  const url = new URL("https://api.agoralia.app/docs/search");
  url.searchParams.set("q", query);
  url.searchParams.set("locale", locale);

  const response = await fetch(url.toString(), {
    method: "GET",
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    if (response.status === 401) {
      throw new Error("Authentication failed - invalid JWT token");
    } else if (response.status === 422) {
      const errorData = await response.json();
      throw new Error(`Validation error: ${JSON.stringify(errorData.detail)}`);
    }
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const results = await searchDocumentation("API keys", "en-US", jwtToken);
results.results.forEach((result) => {
  console.log(`${result.title}: ${result.url} (score: ${result.score.toFixed(2)})`);
});

Limitations

Not Part of Public API

This endpoint is not part of the Public API:

❌ Does not support API key authentication
❌ Requires JWT token (user session)
❌ Intended for internal use within Agoralia application
❌ Not documented in Public API endpoints

For Public API Usage

If you need to search documentation via the Public API:

Use the Public API endpoints for accessing documentation
Or implement your own search functionality
Or contact support for Public API search capabilities

Troubleshooting

401 Unauthorized

Problem: Receiving 401 error even with token.

Solutions:

Verify JWT token is valid and not expired
Ensure token is included in Authorization header with Bearer prefix
Check token has required permissions (viewer role or higher)

No Results Found

Problem: Search returns empty results.

Solutions:

Try different query terms
Check if documentation exists for your tenant
Verify locale matches available documentation languages
Ensure query is at least 2 characters

Slow Search Performance

Problem: Search is slow or times out.

Solutions:

Use more specific queries (fewer results to process)
Cache results for common queries
Implement client-side debouncing for user input

Next Steps

Public API Authentication - Learn about API key authentication (for Public API)
Error Handling - Handle API errors gracefully
Endpoints Reference - See Public API endpoints (this endpoint is not included)

Note

This endpoint is designed for use within the Agoralia web application. For programmatic access to documentation, consider:

Using the Public API endpoints (if available)
Implementing your own search functionality
Contacting support for Public API search capabilities

If you're building an integration, you likely want to use the Public API instead, which uses API key authentication.

Documentation Search API

Overview​

Authentication​

Endpoint​

Query Parameters​

Example Request​

Response Format​

Response Fields​

Language Preference​

Multi-Tenant Support​

Use Cases​

1. Integration with Copilot​

2. Help System​

3. Contextual Documentation​

Error Responses​

401 Unauthorized​

422 Validation Error​

Best Practices​

✅ Use Specific Queries​

✅ Set Locale​

✅ Handle Empty Results​

✅ Cache Results​

Implementation Example​

Python​

JavaScript/TypeScript​

Limitations​

Not Part of Public API​

For Public API Usage​

Troubleshooting​

401 Unauthorized​

No Results Found​

Slow Search Performance​

Next Steps​

Note​

Overview

Authentication

Endpoint

Query Parameters

Example Request

Response Format

Response Fields

Language Preference

Multi-Tenant Support

Use Cases

1. Integration with Copilot

2. Help System

3. Contextual Documentation

Error Responses

401 Unauthorized

422 Validation Error

Best Practices

✅ Use Specific Queries

✅ Set Locale

✅ Handle Empty Results

✅ Cache Results

Implementation Example

Python

JavaScript/TypeScript

Limitations

Not Part of Public API

For Public API Usage

Troubleshooting

401 Unauthorized

No Results Found

Slow Search Performance

Next Steps

Note