# Search many memory spaces (/docs/api/federated-search)
<EndpointLayout>
<EndpointHeader method="POST" path="/v1/dum/federated-search" />

Searches several memory spaces at once and merges the results, best match first. Spaces the key can't reach, or that don't exist, are skipped, and the rest are still searched.

<EndpointExamples>
<CodeTabs items={['cURL']}>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/dum/federated-search \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "memory_space_ids": ["support-space-id", "sales-space-id"],
        "query": "What do we know about Northwind?",
        "top_k": 5
      }'
    ```
  </Tab>
</CodeTabs>

<Tabs items={['200']}>
  <Tab value="200">
    ```json
    [
      {
        "id": "e47a03d9-2c18-4b6f-8e5a-7f1d9c2b0a36",
        "content": "Northwind renewed for two years.",
        "memory_type": "entity",
        "confidence_score": 0.91,
        "memory_space_id": "0b6c2e84-7d19-4a53-b2f0-3e9a1c5d8f47"
      },
      {
        "id": "4c9f1b27-8e63-4d0a-a5b4-1f2e7d9c3a80",
        "content": "Northwind complained about the price increase.",
        "memory_type": "entity",
        "confidence_score": 0.78,
        "memory_space_id": "6a1d4f93-2b7e-4c08-9d35-7e0b2a6c4f19"
      }
    ]
    ```
  </Tab>
</Tabs>
</EndpointExamples>

## Body [#body]

<ApiFields>
  <ApiField name="memory_space_ids" type="string<uuid>[]" required>
    The memory spaces to search, from 1 to 10.
  </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 in total, from 1 to 20.
  </ApiField>
  <ApiField name="end_user" type="string | null">
    Returns only this person's memories, in every space searched.
  </ApiField>
</ApiFields>

## Response [#response]

A list of memories from every space searched, 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.
  </ApiField>
  <ApiField name="[].confidence_score" type="number | null" required>
    How strongly the memory answers the query, from 0 to 1.
  </ApiField>
  <ApiField name="[].memory_space_id" type="string<uuid>" required>
    The memory space the memory came from.
  </ApiField>
</ApiFields>

## Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | The search ran across every space the key can reach. |
| `401` | The key is missing, malformed, or revoked. |
| `422` | A field is missing or invalid, such as more than 10 spaces. |
| `429` | The read rate limit was hit. |

One federated search counts as one read, however many spaces it covers.
</EndpointLayout>
