Skip to main content
POST
/
v1
/
namespaces
/
{namespace_name}
/
documents
/
get
curl -X POST "https://api.moorcheh.ai/v1/namespaces/demo_docs/documents/get" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["doc1"]
  }'

{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'demo_docs'.",
  "requested_ids": 1,
  "found_items": 1,
  "items": [
    {
      "id": "doc1",
      "metadata": {},
      "text": "This is the first document about Moorcheh."
    }
  ]
}

​
Overview

Retrieve specific documents by their IDs from a namespace. This endpoint allows you to fetch documents that have been previously uploaded and indexed. Only documents that exist in the namespace will be returned - non-existent document IDs will be ignored without causing an error.
This endpoint retrieves documents that have been previously uploaded and indexed in the specified namespace. For semantic search and similarity-based retrieval, use the Search API.

​
Authentication

​
x-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json

​
Path Parameters

​
namespace_name
string
required
Name of the namespace containing the documents

​
Request Body

​
ids
array
required
Array of document IDs to retrieve (cannot be empty, max 100 IDs per request)
IDs to use: Use the same chunk/document IDs you provided when uploading text via the public Upload Text API. Pass those IDs in the ids array to retrieve the corresponding documents.
curl -X POST "https://api.moorcheh.ai/v1/namespaces/demo_docs/documents/get" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["doc1"]
  }'

{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'demo_docs'.",
  "requested_ids": 1,
  "found_items": 1,
  "items": [
    {
      "id": "doc1",
      "metadata": {},
      "text": "This is the first document about Moorcheh."
    }
  ]
}

​
Response Fields

​
Success Response (200)

​
status
string
Always “success” for 200 responses
​
message
string
Human-readable confirmation message
​
requested_ids
integer
Number of document IDs requested
​
found_items
integer
Number of documents successfully found and retrieved
​
items
array
Array of retrieved document objects

​
Document Object

​
items[].id
string
Unique identifier of the document
​
items[].text
string
Text content of the document
​
items[].metadata
object
Additional metadata associated with the document

​
Partial Success Response (207)

​
status
string
Always “partial” for 207 responses
​
message
string
Human-readable message describing the partial success
​
requested_ids
integer
Number of document IDs requested
​
found_items
integer
Number of documents successfully found and retrieved
​
not_found_ids
array
Array of document IDs that were not found
​
items
array
Array of successfully retrieved document objects

​
Key Features

Batch Retrieval

Retrieve up to 100 documents in a single request

Partial Success

Non-existent document IDs are ignored without causing errors

Efficient Processing

Uses DynamoDB BatchGetItem for optimal performance

Flexible IDs

Document IDs can be strings or numbers

​
Performance Considerations

  • Use the maximum batch size (100 documents) when possible
  • Group related document retrievals to minimize API calls
  • Consider document size when batching large documents
  • Monitor response times for optimal batch sizes
  • Always check the found_items count vs requested_ids
  • Handle 207 responses gracefully for partial success
  • Implement retry logic for 500 errors with exponential backoff
  • Log missing document IDs for debugging
  • Cache frequently accessed documents client-side
  • Use document IDs as cache keys for efficient lookups
  • Consider TTL based on document update frequency
  • Implement cache invalidation for document updates

​
Use Cases

  • Document Retrieval: Fetch specific documents by ID for display or processing
  • Content Management: Access and manage previously uploaded documents
  • Data Export: Extract documents for backup or migration purposes
  • Quality Assurance: Review uploaded content for accuracy and completeness
  • Integration: Sync document data with external systems and applications
  • Debugging: Investigate and verify document content and metadata