# 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. Hero Light Hero Dark 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