Skip to main content
POST
/
api
/
v1
/
search
Unified search
import requests

url = "https://api.memic.ai/api/v1/search"

payload = {
    "query": "<string>",
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "file_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "environment_slug": "<string>",
    "top_k": 10,
    "min_score": 0.7,
    "include_metadata": True,
    "connector_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "force_route": "structured",
    "metadata_filters": {
        "reference_id": "<string>",
        "reference_ids": ["<string>"],
        "page_number": 2,
        "page_numbers": [123],
        "page_range": {
            "gte": 2,
            "lte": 2
        },
        "category": "<string>",
        "document_type": "<string>"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
{
  "filters_applied": {
    "project_id": "d1710969-5973-4cf1-8c4e-3264158e765f"
  },
  "namespace": "8e9fd1e0-e355-4394-9878-b59ec0fffcfd",
  "query": "quarterly revenue",
  "results": {
    "semantic": [
      {
        "category": "Security",
        "chunk_id": "123e4567-e89b-12d3-a456-426614174000",
        "chunk_index": 5,
        "content": "The cybersecurity landscape shows increasing threats...",
        "file_id": "123e4567-e89b-12d3-a456-426614174001",
        "file_name": "Cyber_Report_2024.pdf",
        "mime_type": "application/pdf",
        "page_number": 3,
        "score": 0.92,
        "tags": [
          "cybersecurity",
          "report"
        ],
        "token_count": 256
      }
    ],
    "structured": {
      "columns": [
        {
          "description": "Customer name",
          "name": "customer",
          "type": "varchar"
        },
        {
          "name": "revenue",
          "type": "integer"
        }
      ],
      "rows": [
        {
          "customer": "Acme",
          "revenue": 50000
        },
        {
          "customer": "Beta",
          "revenue": 75000
        }
      ]
    }
  },
  "routing": {
    "reasoning": "Query combines document search with structured data",
    "route": "hybrid"
  },
  "search_time_ms": 125.5,
  "total_results": 3
}

Authorizations

​
X-API-Key
string
header
required

Memic API key. Every key is bound to exactly one environment — get one from the Memic dashboard under API Keys.

Body

application/json

Request model for semantic search.

​
query
string
required

The search query text

Required string length: 1 - 1000
Example:

"What are the key findings in the cybersecurity report?"

​
project_id
string<uuid> | null

Optional project ID to limit search scope

​
file_ids
string<uuid>[] | null

Optional list of file IDs to limit search scope

​
environment_slug
string | null

Optional environment slug to filter search ('staging' or 'production')

​
top_k
integer
default:10

Number of results to return (max 50)

Required range: 1 <= x <= 50
​
min_score
number
default:0.7

Minimum similarity score threshold (0.0 to 1.0)

Required range: 0 <= x <= 1
​
include_metadata
boolean
default:true

Whether to include file and chunk metadata in results

​
connector_id
string<uuid> | null

Optional: Force query to use a specific connector

​
force_route
enum<string> | null

Optional: Force query routing (structured, semantic, or hybrid)

Available options:
structured,
semantic,
hybrid
​
metadata_filters
MetadataFilters · object

Metadata filters for vector search (reference_id, page_number, etc.). Used in lookup-based search where SQL returns filter values.

Response

Successful Response

Response model for semantic search.

​
query
string
required

Original search query

​
total_results
integer
required

Total number of results returned

​
search_time_ms
number
required

Search execution time in milliseconds

​
namespace
string
required

Organization namespace used for search

​
filters_applied
Filters Applied · object
required

Filters applied to the search

​
results
SearchResults · object

All search results by type

​
routing
RoutingInfo · object

Query routing information