> ## Documentation Index
> Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand Spaces, Documents, and Queries in Orchata

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

<CardGroup cols={2}>
  <Card title="Better Accuracy" icon="bullseye">
    Searching a focused space yields more relevant results than searching everything.
  </Card>

  <Card title="Organization" icon="folder-tree">
    Keep different topics separate - product docs, support articles, research papers.
  </Card>

  <Card title="Access Control" icon="shield">
    All org members can manage spaces; API keys require explicit permissions.
  </Card>

  <Card title="AI Context" icon="brain">
    AI assistants can understand what each space contains and search appropriately.
  </Card>
</CardGroup>

### 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                                       |

<Tip>
  Write detailed descriptions for your spaces. The Smart Query feature uses descriptions to recommend which spaces to search.
</Tip>

### Space Metadata

Attach custom metadata to spaces for categorization and filtering:

```json theme={null}
{
  "name": "Support Docs",
  "description": "Customer support documentation",
  "metadata": {
    "team": "support",
    "region": "us-east",
    "priority": "high"
  }
}
```

You can then filter spaces by metadata when listing:

```bash theme={null}
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

<Info>
  Orchata automatically detects scanned PDFs and uses OCR to extract text content.
</Info>

### 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

<Steps>
  <Step title="pending">
    Document created, waiting for processing.
  </Step>

  <Step title="processing">
    Content is being chunked and embedded.
  </Step>

  <Step title="completed">
    Ready for queries. All chunks are indexed.
  </Step>

  <Step title="failed">
    Processing failed. Check the error message.
  </Step>
</Steps>

<Warning>
  Always check document status before querying. Documents with `status: "processing"` won't return results.
</Warning>

### Metadata

Attach custom metadata to documents for filtering and organization:

```json theme={null}
{
  "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" }`

<Tip>
  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"}`.
</Tip>

## Queries

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

### Standard Query

Search for semantically similar content within specific spaces.

```bash theme={null}
POST /query
{
  "query": "How do I authenticate API requests?",
  "spaceIds": ["spc_abc123"],
  "limit": 10,
  "threshold": 0.7
}
```

**Parameters:**

<ParamField body="query" type="string" required>
  Natural language search query.
</ParamField>

<ParamField body="spaceIds" type="string | string[]" required>
  One or more space IDs to search.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Maximum number of results (1-100).
</ParamField>

<ParamField body="threshold" type="number" default="0.0">
  Minimum similarity score (0-1). Higher values return more relevant but fewer results.
</ParamField>

### Smart Query

Don't know which space to search? Smart Query analyzes your query and recommends relevant spaces based on their descriptions.

```bash theme={null}
POST /query/smart
{
  "query": "How do I install the SDK?",
  "limit": 5
}
```

**Response:**

```json theme={null}
{
  "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
    }
  ]
}
```

<Tip>
  Use Smart Query when building AI agents. It helps agents discover relevant spaces without hardcoding space IDs.
</Tip>

## Putting It Together

Here's a typical workflow for building a RAG application:

<Steps>
  <Step title="Design Your Spaces">
    Plan how to organize your content. Group related documents together.
  </Step>

  <Step title="Upload Documents">
    Add content to each space. Let Orchata handle chunking and embedding.
  </Step>

  <Step title="Use Smart Query">
    When a user asks a question, use Smart Query to find relevant spaces.
  </Step>

  <Step title="Search Spaces">
    Query the recommended spaces with the user's question.
  </Step>

  <Step title="Generate Response">
    Pass the retrieved content to your LLM to generate an answer.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    Learn about API keys and permissions.
  </Card>

  <Card title="MCP Server" icon="plug" href="/mcp/overview">
    Connect AI assistants directly to Orchata.
  </Card>
</CardGroup>