Skip to main content
This guide walks you through creating your first space, uploading a document, and querying your knowledge base.

​
Prerequisites

You’ll need an Orchata account. Sign up at app.orchata.ai if you haven’t already.
New accounts start on the Sandbox tier, which includes 1 space, 50 documents per space, 100 daily API calls, and 7-day data retention. This is perfect for testing and evaluation. View all plans to see tier limits and upgrade options.

​
Step 1: Get Your API Key

1

Navigate to API Keys

Go to API Keys in the Orchata dashboard.
2

Create a New Key

Click Create API Key, give it a name, and copy the key.
Store your API key securely. You won’t be able to see it again after closing the dialog.

​
Step 2: Create a Space

Spaces are containers for related documents. Let’s create one for product documentation. 
curl -X POST https://api.orchata.ai/spaces \
  -H "Oai-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Technical docs for our product"
  }'

{
  "id": "spc_abc123",
  "name": "Product Documentation",
  "description": "Technical docs for our product",
  "slug": "product-documentation",
  "createdAt": "2024-01-15T10:30:00Z"
}
Save the id value - you’ll need it for the next steps.

​
Step 3: Upload a Document

Add your first document to the space. Orchata automatically handles chunking and embedding. 
curl -X POST https://api.orchata.ai/spaces/spc_abc123/documents \
  -H "Oai-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Getting Started\n\nWelcome to our product! This guide will help you get up and running quickly.\n\n## Installation\n\nRun `npm install our-product` to install.\n\n## Configuration\n\nCreate a config file at `~/.config/our-product.json`.",
    "filename": "getting-started.md"
  }'

{
  "id": "doc_xyz789",
  "spaceId": "spc_abc123",
  "filename": "getting-started.md",
  "status": "processing",
  "createdAt": "2024-01-15T10:35:00Z"
}
Documents start with status: "processing". Wait a few seconds for embedding to complete before querying.

​
Step 4: Query Your Knowledge

Now search your knowledge base using natural language. 
curl -X POST https://api.orchata.ai/query \
  -H "Oai-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I install the product?",
    "spaceIds": ["spc_abc123"],
    "limit": 5
  }'

{
  "results": [
    {
      "content": "## Installation\n\nRun `npm install our-product` to install.",
      "score": 0.92,
      "documentId": "doc_xyz789",
      "metadata": {}
    }
  ],
  "query": "How do I install the product?"
}

​
Next Steps

Core Concepts

Deep dive into Spaces, Documents, and Queries.

Authentication

Learn about API keys and permissions.

MCP Setup

Connect AI assistants to your knowledge base.

API Reference

Explore all available endpoints.