Tatry
Docs
Retrieval API

Retrieval API

The Retrieval API provides endpoints for searching and retrieving documents from various sources.

Available Endpoints

EndpointMethodDescription
/v1/retrievePOSTRetrieves documents relevant to a given query
/v1/retrieve/batchPOSTProcesses multiple queries in a single request
/v1/retrieve/historyGETRetrieves a list of recently accessed documents
/v1/retrieve/messageGETRetrieves based on message context from an OpenAI formatted conversation

Endpoints

Document Retrieval

POST /v1/retrieve

Retrieves documents relevant to a given query.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are quantum computers?",
    "max_results": 5
  }' \
  https://api.tatry.dev/v1/retrieve
from tatry import TatryRetriever
 
client = TatryRetriever(api_key="your-api-key")
documents = client.retrieve(
    query="What are quantum computers?", # text of the query to find the relevant documents for
    max_results=5, # number of documents to return
    sources=["medical"], # define sources to return
)

Request Body

{
	"query": "What are quantum computers?",
	"max_results": 5,
	"sources": ["medical"]
}

Response

{
	"documents": [
		{
			"id": "doc_123",
			"content": "Quantum computers are machines that use quantum mechanics...",
			"metadata": {
				"source": "medical",
				"published_date": "2024-01-15",
				"citation": "Standring, S. (Ed.). (2020). Gray's anatomy: The anatomical basis of clinical practice (42nd ed.). Elsevier."
			},
			"relevance_score": 0.95
		}
	],
	"total": 1
}

Batch Retrieval

POST /v1/retrieve/batch

Process multiple queries in a single request.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"query": "quantum computing basics", "max_results": 3},
      {"query": "quantum algorithms", "max_results": 3}
    ]
  }' \
  https://api.tatry.dev/v1/retrieve/batch
from tatry import TatryRetriever
 
client = TatryRetriever(api_key="your-api-key")
results = client.batch_retrieve(
    queries=[
        {"query": "quantum computing basics", "max_results": 3},
        {"query": "quantum algorithms", "max_results": 3}
    ]
)

Request Body

{
	"queries": [
		{
			"query": "quantum computing basics",
			"max_results": 3
		},
		{
			"query": "quantum algorithms",
			"max_results": 3
		}
	]
}

Response

{
	"results": [
		{
			"query_id": 0,
			"documents": [
				{
					"id": "doc_124",
					"content": "The basics of quantum computing involve...",
					"metadata": {
						"title": "Quantum Computing Fundamentals"
					}
				}
			]
		},
		{
			"query_id": 1,
			"documents": [
				{
					"id": "doc_125",
					"content": "Quantum algorithms provide advantages...",
					"metadata": {
						"title": "Understanding Quantum Algorithms"
					}
				}
			]
		}
	]
}

Retrieval History

GET /v1/retrieve/history

Retrieves a list of recently accessed documents.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.tatry.dev/v1/retrieve/history
from tatry import TatryRetriever
 
client = TatryRetriever(api_key="your-api-key")
history = client.get_history()

Query Parameters

ParameterTypeDescription
limitintegerMaximum number of records to return (default: 10)
offsetintegerNumber of records to skip (default: 0)

Response

{
	"history": [
		{
			"document_id": "doc_123",
			"accessed_at": "2024-02-12T10:30:00Z",
			"query": "quantum computing",
			"metadata": {
				"title": "Introduction to Quantum Computing"
			}
		}
	],
	"total": 1
}

Message Context Retrieval

GET /v1/retrieve/message

Retrieves documents based on message context from an OpenAI formatted conversation.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are quantum computers?"},
      {"role": "assistant", "content": "Let me find information about quantum computers."}
    ]
  }' \
  https://api.tatry.dev/v1/retrieve/message
from tatry import TatryRetriever
 
client = TatryRetriever(api_key="your-api-key")
documents = client.retrieve_from_messages(
    messages=[
        {"role": "user", "content": "What are quantum computers?"},
        {"role": "assistant", "content": "Let me find information about quantum computers."}
    ]
)

Request Body

{
	"messages": [
		{
			"role": "user",
			"content": "What are quantum computers?"
		},
		{
			"role": "assistant",
			"content": "Let me find information about quantum computers."
		}
	],
	"max_results": 3
}

Response

{
	"documents": [
		{
			"id": "doc_126",
			"content": "A quantum computer is a device that performs quantum computing...",
			"metadata": {
				"title": "Understanding Quantum Computers",
				"relevance_score": 0.92
			}
		}
	],
	"total": 1
}

Error Handling

The API uses standard HTTP response codes and returns detailed error messages:

{
	"error": {
		"code": "invalid_request",
		"message": "The request was invalid",
		"details": {
			"field": "query",
			"reason": "Query cannot be empty"
		}
	}
}

Common error codes:

  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Invalid API key
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Next Steps

AuthenticationSources