> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmetal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Documents

> Semantically search your embedded documents.

### Auth Headers

<ParamField required header="x-metal-api-key" type="string">
  An API key for your org.
</ParamField>

<ParamField required header="x-metal-client-id" type="string">
  A Client ID for your org.
</ParamField>

### Body

<ParamField body="index" type="string" placeholder="Index ID" required>
  Index ID
</ParamField>

<ParamField body="text" type="string">
  Text
</ParamField>

<ParamField body="imageUrl" type="string">
  Image URL
</ParamField>

<ParamField body="embedding" type="number[]">
  Custom Embeddings
</ParamField>

<ParamField body="ids" type="string[]">
  Subset of documents ids to match
</ParamField>

<ParamField body="filters" type="object">
  <Expandable title="properties">
    <ParamField body="and" type="object[]">
      <Expandable title="properties">
        <ParamField body="field" type="string">
          The name of the filtereable field
        </ParamField>

        <ParamField body="value" type="string or number">
          The field value to search for.
        </ParamField>

        <ParamField body="operator" type="string">
          Possible values: `eq`, `gt`, `gte`, `lt`, `lte`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="or" type="object[]">
      <Expandable title="properties">
        <ParamField body="field" type="string">
          The name of the filtereable field
        </ParamField>

        <ParamField body="value" type="string or number">
          The field value to search for.
        </ParamField>

        <ParamField body="operator" type="string">
          Possible values: `eq`, `gt`, `gte`, `lt`, `lte`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Query

<ParamField query="idsOnly" type="boolean" default="false">
  Return only a list of ids without any metadata.
</ParamField>

<ParamField query="limit" type="number" default="5">
  The limit of possible reponses from your search. Max 100.
</ParamField>

### Response

<ResponseField name="data" type="Results Array">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Id of the embedding
    </ResponseField>

    <ResponseField name="dist" type="string">
      Distance to the vector queried
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Metadata of the embedding
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Example Request theme={null}
  curl --location --request POST 'https://api.getmetal.io/v1/search' \
  --header 'Content-Type: application/json' \
  --header 'x-metal-api-key: <api-key>' \
  --header 'x-metal-client-id: <client-id>' \
  --data-raw '{
      "index": "index-id",
      "text": "Generals gathered in their masses",
      "filters": {
          "and": [{
              "field": "year",
              "value": 1984,
              "operator": "lte"
          }],
          "or": [{
              "field": "name",
              "value": "Iron Maiden",
              "operator": "eq"
          }, {
              "field": "name",
              "value": "Helloween",
              "operator": "eq"
          }]
      }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "dist": "0.666",
        "id": "1",
        "text": "Eagle Fly Free",
        "metadata": {
          "name": "Helloween",
          "year": 1984
        },
        "createdAt":"2023-08-22T18:30:11.493Z"
      },
      {
        "id": "2",
        "dist": "0.999",
        "text": "The Trooper",
        "metadata": {
          "name": "Iron Maiden",
          "year": 1978
        },
        "createdAt": "2023-08-10T11:44:53.010Z"
        }
      }
    ]
  }
  ```
</ResponseExample>