Retrieve chunk results

POST /chunks

This endpoint searches across all data ingested for a user — including events, documents, and summaries — and returns excerpts ranked by semantic relevance.

Purpose

Use this endpoint when your agent or model needs contextual grounding based on a user’s history or profile.
The results can be embedded directly into LLM prompts to personalize reasoning and improve factual recall.

Typical use cases include:

• Chat memory retrieval for ongoing conversations.

• Personalized RAG pipelines in assistants or copilots.

• Cross-tool reasoning and summarization tasks.

Endpoint

Headers

Authorization: x-api-key: <token>

Request Body

Conversation Object

Each element of conversation represents one message in the context window.

Example Request

{
  "user_id": "usr_42af7c",
  "conversation": [
    { "role": "system", "content": "You are an assistant that schedules meetings." },
    { "role": "user", "content": "Can you schedule next week's team sync?" }
  ],
  "top_k": 5
}

Example cURL

curl -X POST "https://api.fastino.ai/chunks" \
  -H "Authorization: x-api-key: sk_test_123" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_42af7c",
    "conversation": [
      {"role": "system", "content": "You are an assistant that schedules meetings."},
      {"role": "user", "content": "Can you schedule next week’s team sync?"}
    ],
    "top_k": 5
  }'

Example Response

{
  "results": [
    {
      "chunk_id": "doc_7#p1",
      "excerpt": "Typical focus blocks 9–12 PT; meetings after 1 PM preferred.",
      "score": 0.84
    },
    {
      "chunk_id": "evt_1#s1",
      "excerpt": "Let's move stand-up to 2 PM starting next week.",
      "score": 0.81
    }
  ]
}

Response Fields

Behavior

• Retrieval results are ranked using Fastino’s adaptive user-specific embeddings.

• Results include both event and document excerpts where relevant.

• top_k controls the number of snippets returned (defaults to 5, max 20).

• Retrieved context can be used for:

  • Model grounding in RAG pipelines.

  • User-aware reasoning and prompt initialization.

  • Personalized summarization or decision support.

Error Responses

Example:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing field: conversation"
  }
}

Example Implementation (Python)

import requests

BASE_URL = "https://api.fastino.ai"
HEADERS = {"Authorization": "x-api-key: sk_live_456", "Content-Type": "application/json"}

payload = {
    "user_id": "usr_42af7c",
    "conversation": [
        {"role": "system", "content": "You are an assistant that schedules meetings."},
        {"role": "user", "content": "Can you schedule next week’s team sync?"}
    ],
    "top_k": 5
}

r = requests.post(f"{BASE_URL}/chunks", json=payload, headers=HEADERS)
for item in r.json()["results"]:
    print(f"{item['excerpt']} (score={item['score']})")

Best Practices

• Keep top_k between 3–8 for optimal LLM prompt context.

• Combine retrieved snippets with /summary results for hybrid reasoning.

• Filter or rerank retrieved chunks in your app for domain-specific weighting.

• Log retrieved chunk_ids if you need traceability between user data and responses.

• Avoid sending empty or truncated conversation arrays — include sufficient context.

Related Endpoints

Summary:
Use POST /chunks to retrieve the most relevant user memory snippets for RAG workflows.
This endpoint powers Fastino’s context-grounded reasoning — allowing agents to access personalized, user-specific information instantly and deterministically.