Search Document Pages

curl --request POST \
  --url https://api.fieldwise.ai/api/v1/documents/search/pages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "alpha": 0.5,
  "metadata_filter": {
    "$and": [
      {
        "category": "research"
      },
      {
        "tags": {
          "$contains": [
            "AI",
            "ML"
          ]
        }
      }
    ]
  },
  "min_relevance": 0.2,
  "optimize_query": true,
  "query": "machine learning algorithms",
  "top_k": 10
}
'

import requests

url = "https://api.fieldwise.ai/api/v1/documents/search/pages"

payload = {
    "alpha": 0.5,
    "metadata_filter": { "$and": [{ "category": "research" }, { "tags": { "$contains": ["AI", "ML"] } }] },
    "min_relevance": 0.2,
    "optimize_query": True,
    "query": "machine learning algorithms",
    "top_k": 10
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alpha: 0.5,
    metadata_filter: {$and: [{category: 'research'}, {tags: {$contains: ['AI', 'ML']}}]},
    min_relevance: 0.2,
    optimize_query: true,
    query: 'machine learning algorithms',
    top_k: 10
  })
};

fetch('https://api.fieldwise.ai/api/v1/documents/search/pages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fieldwise.ai/api/v1/documents/search/pages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'alpha' => 0.5,
    'metadata_filter' => [
        '$and' => [
                [
                                'category' => 'research'
                ],
                [
                                'tags' => [
                                                                '$contains' => [
                                                                                                                                'AI',
                                                                                                                                'ML'
                                                                ]
                                ]
                ]
        ]
    ],
    'min_relevance' => 0.2,
    'optimize_query' => true,
    'query' => 'machine learning algorithms',
    'top_k' => 10
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fieldwise.ai/api/v1/documents/search/pages"

	payload := strings.NewReader("{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fieldwise.ai/api/v1/documents/search/pages")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fieldwise.ai/api/v1/documents/search/pages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "results": [
      {
        "content": "Customer satisfaction metrics show improvement in service quality and response times...",
        "document_id": 678,
        "id": 345,
        "keyword_score": 0.67,
        "page_number": 1,
        "relevance": 0.85,
        "semantic_score": 0.89
      }
    ],
    "optimized_query": "<string>",
    "optimized_metadata": {}
  },
  "success": true,
  "error": {
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "version": "1.0"
  }
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

Documents

Search Document Pages

Advanced hybrid search through document pages with configurable search modes.

Search Modes (Alpha Parameter)

Pure Semantic Search (alpha=1.0, default)

Uses embedding-based similarity matching
Best for: conceptual queries, finding related topics, semantic understanding
Example: “machine learning techniques” finds ML content regardless of exact wording

Pure Keyword Search (alpha=0.0)

Uses PostgreSQL full-text search with ts_rank scoring
Best for: exact terms, names, dates, codes, specific phrases
Example: “Q3 2024 revenue” finds exact financial data mentions

Hybrid Search (0.0 < alpha < 1.0)

Combines both methods with weighted scoring
Best for: balanced results with both conceptual and exact matching
Example: alpha=0.5 gives equal weight to semantic and keyword relevance

Score Normalization

All scores are returned in [0, 1] range using stable, absolute normalization:

Relevance Score: alpha × semantic_score + (1-alpha) × keyword_score
- This is your primary ranking score
- Higher = better match
- Stable across queries (doesn’t change when documents are added/removed)
Semantic Score (0-1): Cosine similarity between query and content embeddings
- Measures conceptual similarity
- 1.0 = identical semantic meaning, 0.0 = completely unrelated
Keyword Score (0-1): PostgreSQL ts_rank with built-in normalization
- Measures exact term matching and frequency
- Mapped to 0-1 range using rank/(rank+1) formula
- Higher scores = more keyword matches, 0.0 = no matching terms

Response Fields

Each result includes:

relevance: Combined score (0-1) - use this for ranking
semantic_score: Semantic component (0-1)
keyword_score: Keyword component (0-1)
content: Full page content
page_number, document_id, id: Identifiers

Usage Guidelines

When to Use Each Mode

Semantic (α=1.0): Exploratory research, concept discovery, broad topics
Keyword (α=0.0): Specific data lookup, exact phrase matching, structured data
Hybrid (α=0.5): General search, balanced relevance, unknown query types
Custom (α=0.2-0.8): Fine-tuned weighting based on specific needs

Best Practices

Start with hybrid search (α=0.5) for unknown query types
Use keyword search (α=0.0) for exact terms, names, dates, codes
Use semantic search (α=1.0) for research and concept exploration
Combine with metadata filters for better performance and precision
Set min_relevance (e.g., 0.3) to filter low-quality results
Results are ordered by relevance score (highest first)

Input Parameters

query (string): Text query (required for α < 1.0)
embedding (array): Pre-computed 1536-dim vector (optional, only for α=1.0)
alpha (float): Search mode weighting (0.0-1.0, default: 1.0)
top_k (int): Max results to return (default: 10)
min_relevance (float): Minimum relevance score 0-1 (default: 0.0)
metadata_filter (object): MongoDB-like filter syntax
created_at_filter (object): Date range filter
updated_at_filter (object): Date range filter
optimize_query (bool): Enable query optimization (default: false)
optimize_metadata (bool): Enable metadata optimization (default: false)

Performance Features

Single optimized database query for all search modes
Workspace-based partitioning for scalability
GIN indexes for fast full-text search
HNSW indexes for fast vector similarity
Database-level filtering and scoring

Example Use Cases

Finding exact product codes:

{"query": "SKU-12345", "alpha": 0.0, "top_k": 5}

Exploring concepts:

{"query": "customer retention strategies", "alpha": 1.0, "top_k": 10}

Balanced search:

{"query": "Q3 revenue growth", "alpha": 0.5, "min_relevance": 0.3}

POST

api

documents

pages

Search Document Pages

curl --request POST \
  --url https://api.fieldwise.ai/api/v1/documents/search/pages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "alpha": 0.5,
  "metadata_filter": {
    "$and": [
      {
        "category": "research"
      },
      {
        "tags": {
          "$contains": [
            "AI",
            "ML"
          ]
        }
      }
    ]
  },
  "min_relevance": 0.2,
  "optimize_query": true,
  "query": "machine learning algorithms",
  "top_k": 10
}
'

import requests

url = "https://api.fieldwise.ai/api/v1/documents/search/pages"

payload = {
    "alpha": 0.5,
    "metadata_filter": { "$and": [{ "category": "research" }, { "tags": { "$contains": ["AI", "ML"] } }] },
    "min_relevance": 0.2,
    "optimize_query": True,
    "query": "machine learning algorithms",
    "top_k": 10
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alpha: 0.5,
    metadata_filter: {$and: [{category: 'research'}, {tags: {$contains: ['AI', 'ML']}}]},
    min_relevance: 0.2,
    optimize_query: true,
    query: 'machine learning algorithms',
    top_k: 10
  })
};

fetch('https://api.fieldwise.ai/api/v1/documents/search/pages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fieldwise.ai/api/v1/documents/search/pages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'alpha' => 0.5,
    'metadata_filter' => [
        '$and' => [
                [
                                'category' => 'research'
                ],
                [
                                'tags' => [
                                                                '$contains' => [
                                                                                                                                'AI',
                                                                                                                                'ML'
                                                                ]
                                ]
                ]
        ]
    ],
    'min_relevance' => 0.2,
    'optimize_query' => true,
    'query' => 'machine learning algorithms',
    'top_k' => 10
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fieldwise.ai/api/v1/documents/search/pages"

	payload := strings.NewReader("{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fieldwise.ai/api/v1/documents/search/pages")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fieldwise.ai/api/v1/documents/search/pages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"alpha\": 0.5,\n  \"metadata_filter\": {\n    \"$and\": [\n      {\n        \"category\": \"research\"\n      },\n      {\n        \"tags\": {\n          \"$contains\": [\n            \"AI\",\n            \"ML\"\n          ]\n        }\n      }\n    ]\n  },\n  \"min_relevance\": 0.2,\n  \"optimize_query\": true,\n  \"query\": \"machine learning algorithms\",\n  \"top_k\": 10\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "results": [
      {
        "content": "Customer satisfaction metrics show improvement in service quality and response times...",
        "document_id": 678,
        "id": 345,
        "keyword_score": 0.67,
        "page_number": 1,
        "relevance": 0.85,
        "semantic_score": 0.89
      }
    ],
    "optimized_query": "<string>",
    "optimized_metadata": {}
  },
  "success": true,
  "error": {
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "version": "1.0"
  }
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

Authorizations

X-API-Key

string

header

required

Headers

X-API-Key

string | null

Body

application/json

Request model for searching document pages with configurable search modes.

Supports three search modes controlled by the alpha parameter:

alpha = 1.0: Pure semantic search using embeddings (default)
alpha = 0.0: Pure keyword search using PostgreSQL full-text search
0.0 < alpha < 1.0: Hybrid search combining both methods with weighted scoring

The search uses proper score normalization to ensure meaningful alpha weighting, returning both combined relevance scores and individual component scores.

query

string | null

The search query (required if embedding not provided)

embedding

number[] | null

Pre-computed embedding vector for search (required if query not provided)

metadata_filter

Metadata Filter · object | null

Optional metadata filters using MongoDB-like query syntax

created_at_filter

Created At Filter · object | null

Filter by created_at database field. Supports operators: $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin. Use ISO date format (e.g., '2024-01-01T00:00:00')

updated_at_filter

Updated At Filter · object | null

Filter by updated_at database field. Supports operators: $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin. Use ISO date format (e.g., '2024-01-01T00:00:00')

top_k

integer

default:10

Number of results to return

Required range: 1 <= x <= 1000

min_relevance

number

default:0

Minimum relevance score (0-1) to filter results. Only results above this threshold will be returned.

Required range: 0 <= x <= 1

optimize_metadata

boolean

default:false

Whether to optimize metadata filter (only works with query, not embedding)

optimize_query

boolean

default:false

Whether to optimize search query (only works with query, not embedding)

alpha

number

default:1

Search weighting: 0.0=pure keyword, 1.0=pure semantic, 0.5=balanced hybrid

Required range: 0 <= x <= 1

Response

Successful Response

Response model for page search.

data

SearchResponseData · object

required

Response data

Show child attributes

success

boolean

default:true

error

ErrorDetail · object | null

Schema for API error responses.

Show child attributes

Example:

{
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found"
}

Documents

Extractions

Tasks

Search Document Pages

Search Modes (Alpha Parameter)

Pure Semantic Search (alpha=1.0, default)

Pure Keyword Search (alpha=0.0)

Hybrid Search (0.0 < alpha < 1.0)

Score Normalization

Response Fields

Usage Guidelines

When to Use Each Mode

Best Practices

Input Parameters

Performance Features

Example Use Cases

Authorizations

Headers

Body

Response