# Delete Document By External Id
Source: https://docs.fieldwise.ai/api-reference/documents/delete-document-by-external-id
delete /api/v1/documents/external/{external_id}
Delete document(s) by external ID with version control.
- **latest_only=true** (default): Deletes only the most recent version of the document
- **latest_only=false**: Deletes all versions of documents with this external_id
Returns the count and IDs of deleted documents.
# Delete Document By Id
Source: https://docs.fieldwise.ai/api-reference/documents/delete-document-by-id
delete /api/v1/documents/internal/{document_id}
Delete a single document by its internal ID.
# Delete Documents By Metadata
Source: https://docs.fieldwise.ai/api-reference/documents/delete-documents-by-metadata
post /api/v1/documents/delete
Delete all documents matching the provided metadata filter.
# Get Document Answer
Source: https://docs.fieldwise.ai/api-reference/documents/get-document-answer
post /api/v1/documents/answer
Answer a question based on the documents matching the provided metadata filter.
The `metadata_filter` parameter supports MongoDB-like query syntax with operators:
- Comparison: `$eq, $ne, $gt, $lt, $gte, $lte, $in, $nin`
- Array: `$contains, $containsAny, $notContains, $size`
- Logical: `$and, $or, $not`
- Type: `$type`
- Regex: `$regex, $iregex`
#### Example Metadata Filter
```json { "$and": [ { "category": "finance" }, { "tags": { "$contains": ["important"] } }, { "$or": [ { "priority": { "$gt": 2 } }, { "status": "active" } ] } ] } ```
# Get Document By External Id
Source: https://docs.fieldwise.ai/api-reference/documents/get-document-by-external-id
get /api/v1/documents/external/{external_id}
Retrieve the latest document by its external ID.
# Get Document By Id
Source: https://docs.fieldwise.ai/api-reference/documents/get-document-by-id
get /api/v1/documents/internal/{document_id}
Retrieve a document by its internal ID.
# Get Document By Task Id
Source: https://docs.fieldwise.ai/api-reference/documents/get-document-by-task-id
get /api/v1/documents/task/{task_identifier}
Retrieve a document by its task identifier.
# Get page content
Source: https://docs.fieldwise.ai/api-reference/documents/get-page-content
get /api/v1/documents/content/pages/{page_id}
Retrieve a specific page by its ID, including all its content.
# Ingest Document
Source: https://docs.fieldwise.ai/api-reference/documents/ingest-document
post /api/v1/documents/ingest
Upload a document and start processing it.
# Ingest Document From Embedding
Source: https://docs.fieldwise.ai/api-reference/documents/ingest-document-from-embedding
post /api/v1/documents/ingest/embedding
Ingest a document directly from a pre-computed embedding vector.
This endpoint allows you to create documents directly from embedding vectors,
bypassing the file upload and text extraction process. This is useful when:
- You already have pre-computed embeddings
- You want to ingest structured data or custom content
- You need to create documents from API responses or generated content
- You want to maintain embedding consistency across systems
The embedding vector must be exactly 1536 dimensions (OpenAI's text-embedding-ada-002 format).
Performance Benefits:
- No file processing overhead
- No text extraction or embedding generation
- Immediate availability for search
- Synchronous operation (completed immediately)
Retrieval:
- Documents can be retrieved using the returned task_identifier via GET /task/{task_identifier}
- External ID retrieval also works via GET /external/{external_id} if provided
Best Practices:
- Ensure embedding vector quality matches your use case
- Include meaningful content text for human readability
- Use consistent metadata structure for filtering
- Consider embedding source and generation method in metadata
# Ingest Document From Url
Source: https://docs.fieldwise.ai/api-reference/documents/ingest-document-from-url
post /api/v1/documents/ingest/url
Ingest a document from a URL.
# List Documents
Source: https://docs.fieldwise.ai/api-reference/documents/list-documents
post /api/v1/documents/list
# Preview Delete By External Id
Source: https://docs.fieldwise.ai/api-reference/documents/preview-delete-by-external-id
get /api/v1/documents/delete/external/{external_id}/preview
Preview which document(s) would be deleted by external ID with version control.
- **latest_only=true** (default): Shows only the most recent version of the document
- **latest_only=false**: Shows all versions of documents with this external_id
Returns the count and IDs of documents that would be deleted.
# Preview Delete By Metadata
Source: https://docs.fieldwise.ai/api-reference/documents/preview-delete-by-metadata
post /api/v1/documents/delete/preview
Preview how many documents would be deleted by the metadata filter.
# Search document pages (deprecated)
Source: https://docs.fieldwise.ai/api-reference/documents/search-document-pages
post /api/v1/documents/pages/search
Get the most relevant pages from documents matching the provided metadata filter.
The `metadata_filter` parameter supports the same MongoDB-like query syntax as the [/answer](api-reference/documents/get-document-answer) endpoint. See [/answer](api-reference/documents/get-document-answer) endpoint documentation for detailed examples of metadata filtering.
# Search Document Pages
Source: https://docs.fieldwise.ai/api-reference/documents/search-document-pages-1
post /api/v1/documents/search/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:**
```json
{"query": "SKU-12345", "alpha": 0.0, "top_k": 5}
```
**Exploring concepts:**
```json
{"query": "customer retention strategies", "alpha": 1.0, "top_k": 10}
```
**Balanced search:**
```json
{"query": "Q3 revenue growth", "alpha": 0.5, "min_relevance": 0.3}
```
# Update Document By External Id
Source: https://docs.fieldwise.ai/api-reference/documents/update-document-by-external-id
patch /api/v1/documents/external/{external_id}/metadata
Update a single document by its external ID.
# Update Document By Id
Source: https://docs.fieldwise.ai/api-reference/documents/update-document-by-id
patch /api/v1/documents/internal/{document_id}/metadata
Update a single document by its internal ID.
# Get Extraction Result By Id
Source: https://docs.fieldwise.ai/api-reference/extractions/get-extraction-result-by-id
get /api/v1/extractions/results/internal/{result_id}
Retrieve an extraction result by its ID.
# Get Extraction Result By Task Id
Source: https://docs.fieldwise.ai/api-reference/extractions/get-extraction-result-by-task-id
get /api/v1/extractions/results/task/{task_identifier}
Retrieve an extraction result by its task identifier.
# Run Extraction From File
Source: https://docs.fieldwise.ai/api-reference/extractions/run-extraction-from-file
post /api/v1/extractions/run
Run extraction on an uploaded file.
# Run Extraction From Url
Source: https://docs.fieldwise.ai/api-reference/extractions/run-extraction-from-url
post /api/v1/extractions/run/url
Run extraction on a file from URL.
# Get Task Status
Source: https://docs.fieldwise.ai/api-reference/tasks/get-task-status
get /api/v1/tasks/status/{task_identifier}
Get the status of any processing task.
# Introduction
Source: https://docs.fieldwise.ai/introduction
Welcome to the Fieldwise API documentation. Our API offers a developer-friendly interface to enhance your document intelligence by providing real-time data retrieval and AI-driven insights.
The Fieldwise API offers various endpoints to manage and retrieve information:
* **Document Management**: Upload, update, and delete documents in your repository.
* **Search**: Perform searches across your documents using AI-driven filters to quickly find relevant information.
* **Metadata Filtering**: Apply metadata filters to narrow down search results based on specific criteria.
* **Question Answering**: Submit queries to receive answers based on the content of your documents.
For a comprehensive list of endpoints and their detailed usage, please refer to the [API reference](/api-reference).
## Rate Limiting
To ensure optimal performance and fair usage, the Fieldwise API enforces rate limits. The default rate limit is 100 requests per minute. If you require a higher rate limit, please contact our support team to discuss your needs.
## Base URL
The Fieldwise API is accessible at: [https://api.fieldwise.ai/api/v1/](https://api.fieldwise.ai/api/v1/).
# Quickstart
Source: https://docs.fieldwise.ai/quickstart
Welcome to the Fieldwise API! This guide will help you get started with authentication and making your first API request.
## Step 1: Sign Up & Generate Your API Token
To access the Fieldwise API, you need an API token. Follow these steps to get one:
1. Go to [app.fieldwise.ai](https://app.fieldwise.ai/) and create an account.
2. Log in and navigate to the **API Keys** section.
3. Generate your personal API token.
4. Copy the token and store it securely.
Your API requests must include this token in the `X-Api-Key` header.
## Step 2: Make Your First API Request
Once you have your API token, you can start interacting with the Fieldwise API.
# Webhooks
Source: https://docs.fieldwise.ai/webhook
Receive real-time notifications when documents are processed
## Overview
Webhooks allow your application to receive real-time HTTP notifications when events occur in FieldWise. Instead of polling the API, webhooks push data to your endpoint instantly.
## Supported Events
| Event | Description |
| ------------------------------- | ------------------------------- |
| `document.processing.started` | Document processing has begun |
| `document.processing.completed` | Document processed successfully |
| `document.processing.failed` | Document processing failed |
## Webhook Payload
```json theme={null}
{
"event": "document.processing.completed",
"timestamp": "2026-01-16T10:09:57.792Z",
"data": {
"task_identifier": "DocumentExtraction:a29f03e7-5a95-49a6-a845-ef90b15d0b31",
"document_id": 164,
"external_id": null,
"status": "completed",
"message": "Document processing completed",
"file_name": "invoice.pdf"
}
}
```
### Payload Fields
| Field | Type | Description |
| ---------------------- | --------------- | -------------------------------------- |
| `event` | string | Event type (dot-notation) |
| `timestamp` | string | ISO 8601 timestamp |
| `data.task_identifier` | string | Unique task ID for tracking |
| `data.document_id` | integer \| null | Document ID (available on completion) |
| `data.external_id` | string \| null | Your custom reference ID |
| `data.status` | string | `processing`, `completed`, or `failed` |
| `data.message` | string | Human-readable status description |
| `data.file_name` | string | Original file name |
## Security Headers
Every webhook includes these headers:
| Header | Description |
| ----------------------- | --------------------------- |
| `X-FieldWise-Signature` | HMAC-SHA256 signature |
| `X-FieldWise-Timestamp` | Timestamp used in signature |
| `X-FieldWise-Event` | Event type |
## Signature Verification
**Always verify webhook signatures** to ensure requests come from FieldWise.
```javascript Node.js theme={null}
const crypto = require('crypto');
function verifyWebhook(rawBody, signature, timestamp, secret) {
// 1. Check timestamp is recent (5 min)
const age = Math.abs(Date.now() - new Date(timestamp).getTime()) / 1000;
if (age > 300) return false;
// 2. Compute expected signature
const message = `${timestamp}.${rawBody}`;
const expected = crypto
.createHmac('sha256', secret)
.update(message)
.digest('hex');
// 3. Compare (constant-time)
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express.js example
app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-fieldwise-signature'];
const timestamp = req.headers['x-fieldwise-timestamp'];
if (!verifyWebhook(req.body.toString(), signature, timestamp, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
console.log('Received:', event.event, event.data.status);
res.status(200).send('OK');
});
```
```python Python theme={null}
import hmac
import hashlib
from datetime import datetime, timezone
from flask import Flask, request
def verify_webhook(payload, signature, timestamp, secret):
# Check timestamp is recent
webhook_time = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
age = abs((datetime.now(timezone.utc) - webhook_time).total_seconds())
if age > 300:
return False
# Compute expected signature
message = f"{timestamp}.{payload}"
expected = hmac.new(
key=secret.encode(),
msg=message.encode(),
digestmod=hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
# Flask example
@app.route('/webhooks', methods=['POST'])
def handle_webhook():
signature = request.headers.get('X-FieldWise-Signature')
timestamp = request.headers.get('X-FieldWise-Timestamp')
if not verify_webhook(request.data.decode(), signature, timestamp, WEBHOOK_SECRET):
return 'Invalid signature', 401
event = request.json
print(f"Received: {event['event']} - {event['data']['status']}")
return 'OK', 200
```
## Retry Policy
Failed deliveries are automatically retried:
| Attempt | Delay |
| --------- | ----------- |
| 1st retry | 30 seconds |
| 2nd retry | 60 seconds |
| 3rd retry | 120 seconds |
After 3 failed attempts, the webhook is marked as failed.
## Best Practices
Return `200 OK` immediately, then process asynchronously. Timeout is 30 seconds.
Use `task_identifier` to deduplicate. Webhooks may be delivered more than once.
Always use HTTPS endpoints in production to protect webhook payloads.
Always verify the `X-FieldWise-Signature` header before processing.
## Managing Webhooks
Configure webhooks directly in the FieldWise dashboard under **Settings → Webhooks**. From there you can:
* Create new webhooks
* Edit webhook settings
* Delete webhooks
* Send test payloads
* Rotate secrets