Your First Document
This guide walks you through uploading your first document and searching it. You will use the sample Wikipedia article about Malaysia included in the repository.
Before You Begin
Make sure you have:
- Your
.envfile set up - Services running
- A terminal open
- An API key
- The sample file at
test-documents/malaysia-wikipedia.txt
Step 1: Start the Services
just prod-up
just status
Wait for all services to become healthy before continuing.
Step 2: Upload a Sample Document
curl -X POST http://localhost:8000/embed \
-H "X-API-Key: super-secret-key" \
-F "file=@test-documents/malaysia-wikipedia.txt" \
-F "document_id=malaysia-wiki-001"
Example response:
{
"job_id": "c72483596a8a4b54b007bd24cc8a183e",
"document_id": "malaysia-wiki-001",
"status": "pending"
}
For interactive terminal use, you can run just embed test-documents/malaysia-wikipedia.txt instead of the curl command above. The just command handles upload, polling, and displays a summary automatically.
Note: The just commands are developer convenience tools for terminal access only. For programmatic API calls from applications, use the curl/HTTP examples shown in this guide.
Step 3: Wait for Processing
curl http://localhost:8000/status/c72483596a8a4b54b007bd24cc8a183e \
-H "X-API-Key: super-secret-key"
When processing finishes, /status/{job_id} returns the completed upload and extracted entities. In this real run, classification metadata was finalized later in search/document results:
{
"job_id": "c72483596a8a4b54b007bd24cc8a183e",
"document_id": "malaysia-wiki-001",
"status": "completed",
"chunks_created": 11,
"categories": [],
"classification_status": "pending",
"created_at": "2026-06-11T16:36:17.653095+08:00",
"completed_at": "2026-06-11T16:36:32.572404+08:00",
"entities_extracted": {
"persons": [
"Malaisia",
"Malesia",
"Borneo",
"Sarawak",
"Islam"
],
"organizations": [
"Wikipedia",
"the Malayan Union",
"the Federation of Malaya",
"the Organisation of Islamic Cooperation (OIC",
"the Association of Southeast Asian Nations"
],
"dates": [
"the 18th century",
"three years",
"1946",
"1948",
"31 August 1957"
],
"locations": [
"Malaya",
"Malaysia",
"Southeast Asia",
"South China Sea",
"Peninsular"
],
"monetary_amounts": [
"34 million",
"3 million",
"2 million"
],
"account_numbers": [],
"transaction_refs": [],
"account_types": []
}
}
If you do not want to poll manually, run a small loop until the status becomes completed.
Step 4: Search Your Document
curl -X POST http://localhost:8000/search \
-H "X-API-Key: super-secret-key" \
-H "Content-Type: application/json" \
-d '{"query": "capital of Malaysia", "limit": 5}'
For interactive terminal use, you can run just search "capital of Malaysia" instead of the curl command above. The just command displays a concise summary with a compact results table. Use --json for the full API response.
Note: The just commands are developer convenience tools for terminal access only. For programmatic API calls from applications, use the curl/HTTP examples shown in this guide.
Example response:
{
"results": [
{
"id": "36c2a767-eb81-c7b1-6de7-d0cc6cde77d4",
"score": {
"value": 1.0,
"rerank": null,
"strategy": "hybrid"
},
"document": {
"id": "malaysia-wiki-001",
"created_at": "2026-06-11T16:36:17.653095+08:00"
},
"chunk": {
"id": "malaysia-wiki-001:0",
"index": 0,
"text": "MALAYSIA ======== From Wikipedia, the free encyclopedia Not to be confused with Malaisia, Malesia, or Malaya. ----------------------------------------------------------------------------- OVERVIEW ----------------------------------------------------------------------------- Malaysia is a country in Southeast Asia. A federal constitutional monarchy, it consists of 13 states and three federal territories, separated by ...",
"page": null
},
"classification": {
"categories": [],
"status": "pending"
},
"entities": {
"persons": [
"Malaisia",
"Malesia",
"Borneo",
"Sarawak"
],
"organizations": [
"Wikipedia",
"the Malayan Union",
"the Federation of Malaya"
],
"dates": [
"the 18th century",
"three years",
"1946",
"1948",
"31 August 1957",
"16 September 1963",
"August 1965"
],
"locations": [
"Malaya",
"Malaysia",
"Southeast Asia",
"South China Sea",
"Peninsular",
"East Malaysia",
"Thailand",
"Singapore",
"Vietnam",
"Indonesia",
"Brunei",
"Philippines",
"Kuala Lumpur",
"Putrajaya",
"the British Empire",
"Straits",
"British Malaya",
"Japan",
"North Borneo"
],
"monetary_amounts": [
"34 million"
],
"account_numbers": [],
"transaction_refs": [],
"account_types": []
},
"metadata": {
"schema_version": "2",
"source": {
"filename": "malaysia-wikipedia.txt",
"mime_type": "text/plain",
"extension": "txt"
},
"document": {},
"location": {
"page_number": 1,
"page_label": "1",
"chunk_index": 0
},
"classification": {
"status": "pending",
"categories": []
},
"quality": {
"text_extraction": "native",
"ocr_used": false,
"warnings": []
},
"custom": {}
}
}
],
"meta": {
"query": "capital of Malaysia",
"total": 10,
"offset": 0,
"limit": 5,
"has_more": true,
"query_time_ms": 15,
"retrieval": {
"alpha": 0.5,
"reranked": false
},
"applied_filters": {}
}
}
Try Two More Searches
curl -X POST http://localhost:8000/search \
-H "X-API-Key: super-secret-key" \
-H "Content-Type: application/json" \
-d '{"query": "When did Malaysia gain independence?", "limit": 5}'
curl -X POST http://localhost:8000/search \
-H "X-API-Key: super-secret-key" \
-H "Content-Type: application/json" \
-d '{"query": "What languages are spoken in Malaysia?", "limit": 5}'
Common Problems
| Problem | Cause | Solution |
|---|---|---|
connection refused | Services not running | Run just prod-up |
401 Unauthorized | Wrong API key | Check API_KEY_CLIENTS in .env, for example API_KEY_CLIENTS={"super-secret-key":"demo-client"} |
| No search results | Document still processing | Wait for status completed |
Document stuck on pending | Workers not running | Check with just status |
File not found | Wrong directory | Run from project root |
What's Next
- Learn about categories → Auto-Categorizing Your Documents
- Working with images and OCR → OCR Guide
- Advanced search options → Embeddings and Retrieval
- API reference → Search API