# Search memories (/docs/api/search)
<EndpointLayout>
<EndpointHeader method="POST" path="/v1/dum/search" />

Searches one memory space and returns the most relevant, current memories, best match first. `lynk.recall` calls it for you.

<EndpointExamples>
<CodeTabs>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/dum/search \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "memory_space_id": "your-memory-space-id",
        "query": "How does Maya like to be contacted?",
        "top_k": 5,
        "end_user": "user_8f2c"
      }'
    ```
  </Tab>
  <Tab value="Python">
    ```python
    from docklee import Lynk

    lynk = Lynk(memory_space_id="your-memory-space-id")
    records = lynk.recall_sync("How does Maya like to be contacted?", end_user="user_8f2c")
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import { Lynk } from 'docklee';

    const lynk = new Lynk({ memorySpaceId: 'your-memory-space-id' });
    const records = await lynk.recall('How does Maya like to be contacted?', { endUser: 'user_8f2c' });
    ```
  </Tab>
</CodeTabs>

<Tabs items={['200', '403']}>
  <Tab value="200">
    ```json
    [
      {
        "id": "9b1e7c42-5d3a-4f08-b6e2-1a7c0d93e5f4",
        "content": "Maya prefers email over phone calls.",
        "memory_type": "entity",
        "confidence_score": 0.87
      }
    ]
    ```
  </Tab>
  <Tab value="403">
    ```json
    {
      "detail": "API key does not allow search access."
    }
    ```
  </Tab>
</Tabs>
</EndpointExamples>

## Body [#body]

<ApiFields>
  <ApiField name="memory_space_id" type="string<uuid>" required>
    The memory space to search.
  </ApiField>
  <ApiField name="query" type="string" required>
    The question, in plain words.
  </ApiField>
  <ApiField name="top_k" type="integer" defaultValue="5">
    How many memories to return, from 1 to 50.
  </ApiField>
  <ApiField name="end_user" type="string | null">
    Returns only this person's memories, up to 255 characters. Required in a multi-user space, where a search without it returns `[]`. See [End users](/docs/docklee/end-users).
  </ApiField>
</ApiFields>

## Response [#response]

A list of memories, best match first.

<ApiFields>
  <ApiField name="[].id" type="string<uuid>" required>
    The memory's ID.
  </ApiField>
  <ApiField name="[].content" type="string" required>
    The remembered text.
  </ApiField>
  <ApiField name="[].memory_type" type="string" required>
    The storage class. See [Memory types](/docs/memory/memory-types).
  </ApiField>
  <ApiField name="[].confidence_score" type="number | null" required>
    How strongly the memory answers the query, from 0 to 1.
  </ApiField>
</ApiFields>

## Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | The search ran. An empty list means nothing matched. |
| `401` | The key is missing, malformed, or revoked. |
| `403` | The key's capability or scope doesn't allow searching this memory space. |
| `404` | The memory space doesn't exist in the key's workspace. |
| `422` | A field is missing or invalid, such as `top_k` above 50. |
| `429` | The read rate limit was hit. |
</EndpointLayout>
