Core Concepts

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

Property	Description
`id`	Unique identifier (e.g., `spc_abc123`)
`name`	Human-readable name
`description`	Explains what the space contains - used by Smart Query
`slug`	URL-friendly identifier
`icon`	Optional emoji icon
`metadata`	Custom key-value pairs for filtering and organization
`isArchived`	Soft-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

Keep spaces focused - A space for “Product Documentation” is better than “Everything”
Use descriptive names - Make it obvious what content lives there
Write good descriptions - Help AI understand the space’s purpose
Use metadata for categorization - Tag spaces with team, region, or project info for easy filtering
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:

Chunks the content into smaller pieces
Embeds each chunk using AI models
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

Property	Description
`id`	Unique identifier (e.g., `doc_xyz789`)
`spaceId`	Parent space ID
`filename`	Original filename
`status`	Processing status: `pending`, `processing`, `completed`, `failed`
`metadata`	Custom key-value pairs
`chunkCount`	Number of chunks after processing

Document Status

pending

Document created, waiting for processing.

processing

Content is being chunked and embedded.

completed

Ready for queries. All chunks are indexed.

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:

string

required

Natural language search query.

string | string[]

required

One or more space IDs to search.

integer

default:"10"

Maximum number of results (1-100).

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:

Design Your Spaces

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

Upload Documents

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

Use Smart Query

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

Search Spaces

Query the recommended spaces with the user’s question.

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.

Getting Started

MCP Server

AI Tool Setup

CLI

TypeScript SDK

Spaces

Why Spaces Matter

Better Accuracy

Organization

Access Control

AI Context

Space Properties

Space Metadata

Best Practices

Documents

Supported Content

Document Properties

Document Status

Metadata

Queries

Standard Query

Smart Query

Putting It Together

Next Steps

Authentication

MCP Server

​Spaces

​Why Spaces Matter

Better Accuracy

Organization

Access Control

AI Context

​Space Properties

​Space Metadata

​Best Practices

​Documents

​Supported Content

​Document Properties

​Document Status

​Metadata

​Queries

​Standard Query

​Smart Query

​Putting It Together

​Next Steps

Authentication

MCP Server

Spaces

Why Spaces Matter

Space Properties

Space Metadata

Best Practices

Documents

Supported Content

Document Properties

Document Status

Metadata

Queries

Standard Query

Smart Query

Putting It Together

Next Steps