Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Fetch stored items by id within a namespace. Item ids are unique per namespace, not globally.
  • Text namespaces return id, text, and metadata for each found item
  • Vector namespaces return id and metadata only (vectors are not returned)
Ids that do not exist are omitted from items; the request still succeeds with found_items less than requested_ids.

​
Method

client.get_namespace_items(namespace_name: str, payload: dict) -> dict

​
API

POST /namespaces/{namespace_name}/items/get — see Get items

​
Parameters

​
namespace_name
string
required
Namespace to read from.
​
ids
array
required
Non-empty array of item id strings. Maximum 100 ids per request.

​
Example

from moorcheh import MoorchehApiClient, MoorchehApiError

client = MoorchehApiClient("http://localhost:8080")

# Text namespace
result = client.get_namespace_items("my-documents", {
    "ids": ["doc-1", "doc-2"],
})

for item in result["items"]:
    print(item["id"], item.get("text"), item["metadata"])

# Vector namespace (no text or vector in response)
result = client.get_namespace_items("my-embeddings", {
    "ids": ["vec-1"],
})

for item in result["items"]:
    print(item["id"], item["metadata"])

​
Returns

​
status
string
"success" when the lookup completed.
​
message
string
Human-readable result description.
​
requested_ids
number
Number of ids sent in the request.
​
found_items
number
Number of items returned in items. May be less than requested_ids if some ids were not found.
​
items
array
Array of found items. Empty when none of the requested ids exist.
​
items[].id
string
Item id.
​
items[].text
string
Stored document text. Present for text namespace items only.
​
items[].metadata
object
Metadata stored with the item (custom fields from upload).
Example return value (text namespace)
{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'my-documents'.",
  "requested_ids": 2,
  "found_items": 1,
  "items": [
    {
      "id": "doc-1",
      "metadata": {"team": "ai"},
      "text": "Moorcheh on-prem retrieval test",
    },
  ],
}
Example return value (vector namespace)
{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'my-embeddings'.",
  "requested_ids": 1,
  "found_items": 1,
  "items": [
    {
      "id": "vec-1",
      "metadata": {"source": "demo"},
    },
  ],
}

​
Errors

Non-2xx responses raise MoorchehApiError. A successful lookup with missing ids does not raise — check found_items vs requested_ids. 
from moorcheh import MoorchehApiError

try:
    result = client.get_namespace_items("my-documents", {"ids": ["doc-1"]})
except MoorchehApiError as e:
    print(e.status_code, e.body)
StatusCause
400Empty ids, more than 100 ids, or empty id string
404Namespace not found
  • Maximum 100 ids per request — use multiple requests for larger batches
  • Missing ids are skipped; check found_items vs requested_ids
  • Vector embeddings are not included in the response