Hindsight Cloud Docs

Appearance

Reflect and generate answer ​

POST /v1/default/banks/{bank_id}/reflect

Reflect and formulate an answer using bank identity, world facts, and opinions.

This endpoint:

  1. Retrieves experience (conversations and events)
  2. Retrieves world facts relevant to the query
  3. Retrieves existing opinions (bank's perspectives)
  4. Uses LLM to formulate a contextual answer
  5. Returns plain text answer and the facts used

Authentication required — include an Authorization: Bearer hsk_... header. See Authentication for details.

Path Parameters ​

NameTypeRequiredDescription
bank_idstringYes

Request Body ​

Content-Type: application/json

json
{
  "budget": "low",
  "include": {
    "facts": {}
  },
  "max_tokens": 4096,
  "query": "What do you think about artificial intelligence?",
  "response_schema": {
    "properties": {
      "summary": {
        "type": "string"
      },
      "key_points": {
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": [
      "summary",
      "key_points"
    ],
    "type": "object"
  },
  "tags": [
    "user_a"
  ],
  "tags_match": "any"
}

Example Request ​

bash
curl -X POST 'https://api.hindsight.vectorize.io/v1/default/banks/your-bank-id/reflect' \
  -H 'Authorization: Bearer hsk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "budget": "low",
    "include": {
      "facts": {}
    },
    "max_tokens": 4096,
    "query": "What do you think about artificial intelligence?",
    "response_schema": {
      "properties": {
        "summary": {
          "type": "string"
        },
        "key_points": {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "summary",
        "key_points"
      ],
      "type": "object"
    },
    "tags": [
      "user_a"
    ],
    "tags_match": "any"
  }'

Responses ​

200 — Successful Response

json
{
  "based_on": {
    "memories": [
      {
        "id": "123",
        "text": "AI is used in healthcare",
        "type": "world"
      },
      {
        "id": "456",
        "text": "I discussed AI applications last week",
        "type": "experience"
      }
    ]
  },
  "structured_output": {
    "key_points": [
      "Used in healthcare",
      "Discussed recently"
    ],
    "summary": "AI is transformative"
  },
  "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  "trace": {
    "llm_calls": [
      {
        "duration_ms": 1200,
        "scope": "agent_1"
      }
    ],
    "observations": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "recall"
      }
    ]
  },
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}

422 — Validation Error

json
{
  "detail": [
    {
      "loc": [
        null
      ],
      "msg": "Message",
      "type": "Error Type",
      "input": null,
      "ctx": {},
      "url": "URL"
    }
  ]
}

Source: /v1/default/banks/{bank_id}/reflect