---
title: "Retrieve"
method: POST
path: "/api/assistant/retrieve"
tags: ["assistant"]
---

# Retrieve

`POST /api/assistant/retrieve`

Retrieve relevant document chunks for a user message.
Returns tool responses with context from documents without generating an answer.

## Headers

- `workspace-key` string

## Request body

- MessageInput
  - `content` string, required
  - `tools` object
  - `workspace_ext_id` string, required
  - `parent_message_ext_id` string, nullable
  - `config_ext_id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-21** `1f956ac3d1c1` — 2 info
  - added the new optional request property `tools/additionalProperties/oneOf[subschema #2: RetrievalChunkTool]/tool_responses/additionalProperties/items/metadata/heading`
  - added the new optional request property `tools/additionalProperties/oneOf[subschema #3: RetrievalFullContextTool]/tool_responses/additionalProperties/items/metadata/heading`
- **2025-10-28** `849d5e8732f6` — 3 info
  - added the new optional `header` request parameter `workspace-key`
  - added `trace` discriminator mapping keys to the `tools/additionalProperties/` request property
  - added `#/components/schemas/TraceTool` to the `tools/additionalProperties/` request property `oneOf` list
- **2025-10-06** `8d3e894e6c0b` — 6 breaking
  - added the new required request property `tools/additionalProperties/oneOf[subschema #1: ModelCitationTool]/tool_responses/additionalProperties/chunk_ids`
  - added the new required request property `tools/additionalProperties/oneOf[subschema #1: ModelCitationTool]/tool_responses/additionalProperties/offset_end`
  - added the new required request property `tools/additionalProperties/oneOf[subschema #1: ModelCitationTool]/tool_responses/additionalProperties/offset_start`
  - added the new required request property `tools/additionalProperties/oneOf[subschema #1: ModelCitationTool]/tool_responses/additionalProperties/statement`
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/arbicity/apis/arbi/changes/api/assistant/retrieve/post.md)

---

[API](https://skmtc.dev/arbicity/apis/arbi.md) · [All operations](https://skmtc.dev/arbicity/apis/arbi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arbicity/arbi/revisions/1f956ac3d1c1/schema)