Skip to main content
Orchata organizes information using three core concepts: Spaces, Documents, and Queries. Understanding these will help you design effective knowledge bases.

​
Spaces

A Space is a logical container for related documents. Think of it as a folder with superpowers - it not only organizes your content but also provides semantic context for searches.

​
Why Spaces Matter

Better Accuracy

Searching a focused space yields more relevant results than searching everything.

Organization

Keep different topics separate - product docs, support articles, research papers.

Access Control

Control who can access which spaces via API key permissions.

AI Context

AI assistants can understand what each space contains and search appropriately.

​
Space Properties

PropertyDescription
idUnique identifier (e.g., spc_abc123)
nameHuman-readable name
descriptionExplains what the space contains - used by Smart Query
slugURL-friendly identifier
iconOptional emoji icon
isArchivedSoft-delete flag
Write detailed descriptions for your spaces. The Smart Query feature uses descriptions to recommend which spaces to search.

​
Best Practices

  1. Keep spaces focused - A space for “Product Documentation” is better than “Everything”
  2. Use descriptive names - Make it obvious what content lives there
  3. Write good descriptions - Help AI understand the space’s purpose
  4. Archive, don’t delete - Archiving preserves data while hiding the space

​
Documents

A Document is a piece of content within a space. When you upload a document, Orchata automatically:
  1. Chunks the content into smaller pieces
  2. Embeds each chunk using AI models
  3. Indexes the embeddings for fast similarity search

​
Supported Content

Currently, Orchata supports:
  • PDF
  • Word documents
  • Excel documents
  • PowerPoint documents
  • Markdown files
  • Plain text files
  • Images
Orchata automatically detects scanned PDFs and uses OCR to extract text content.

​
Document Properties

PropertyDescription
idUnique identifier (e.g., doc_xyz789)
spaceIdParent space ID
filenameOriginal filename
statusProcessing status: pending, processing, completed, failed
metadataCustom key-value pairs
chunkCountNumber of chunks after processing

​
Document Status

1

pending

Document created, waiting for processing.
2

processing

Content is being chunked and embedded.
3

completed

Ready for queries. All chunks are indexed.
4

failed

Processing failed. Check the error message.
Always check document status before querying. Documents with status: "processing" won’t return results.

​
Metadata

Attach custom metadata to documents for filtering and organization: 
{
  "content": "# API Reference...",
  "filename": "api-reference.md",
  "metadata": {
    "version": "2.0",
    "author": "engineering",
    "category": "technical"
  }
}

​
Queries

Orchata provides two types of queries for searching your knowledge base.

​
Standard Query

Search for semantically similar content within specific spaces. 
POST /query
{
  "query": "How do I authenticate API requests?",
  "spaceIds": ["spc_abc123"],
  "limit": 10,
  "threshold": 0.7
}
Parameters:
​
query
string
required
Natural language search query.
​
spaceIds
string | string[]
required
One or more space IDs to search.
​
limit
integer
default:"10"
Maximum number of results (1-100).
​
threshold
number
default:"0.0"
Minimum similarity score (0-1). Higher values return more relevant but fewer results.

​
Smart Query

Don’t know which space to search? Smart Query analyzes your query and recommends relevant spaces based on their descriptions. 
POST /query/smart
{
  "query": "How do I install the SDK?",
  "limit": 5
}
Response: 
{
  "recommendations": [
    {
      "spaceId": "spc_abc123",
      "name": "SDK Documentation",
      "description": "Installation guides and API reference for our SDK",
      "relevanceScore": 0.89
    },
    {
      "spaceId": "spc_def456",
      "name": "Tutorials",
      "description": "Step-by-step guides for common tasks",
      "relevanceScore": 0.72
    }
  ]
}
Use Smart Query when building AI agents. It helps agents discover relevant spaces without hardcoding space IDs.

​
Putting It Together

Here’s a typical workflow for building a RAG application:
1

Design Your Spaces

Plan how to organize your content. Group related documents together.
2

Upload Documents

Add content to each space. Let Orchata handle chunking and embedding.
3

Use Smart Query

When a user asks a question, use Smart Query to find relevant spaces.
4

Search Spaces

Query the recommended spaces with the user’s question.
5

Generate Response

Pass the retrieved content to your LLM to generate an answer.

​
Next Steps

Authentication

Learn about API keys and permissions.

MCP Server

Connect AI assistants directly to Orchata.