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

All org members can manage spaces; API keys require explicit 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
metadataCustom key-value pairs for filtering and organization
isArchivedSoft-delete flag
Write detailed descriptions for your spaces. The Smart Query feature uses descriptions to recommend which spaces to search.

​
Space Metadata

Attach custom metadata to spaces for categorization and filtering: 
{
  "name": "Support Docs",
  "description": "Customer support documentation",
  "metadata": {
    "team": "support",
    "region": "us-east",
    "priority": "high"
  }
}
You can then filter spaces by metadata when listing: 
GET /spaces?metadata={"team":"support"}

​
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. Use metadata for categorization - Tag spaces with team, region, or project info for easy filtering
  5. 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"
  }
}
Metadata enables powerful filtering across the platform:
  • List documents - Filter by any metadata key-value pair: GET /documents?spaceId=spc_123&metadata={"author":"engineering"}
  • Query - Only search documents matching specific metadata: POST /query with metadata: { category: "technical" }
Metadata filtering uses partial matching - you only need to specify the keys you want to filter by. A document with {"version": "2.0", "author": "engineering"} will match a filter of {"author": "engineering"}.

​
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.