Skip to main content

​
API Reference

The FLTR API is organized around REST principles. It has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

​
Base URL

https://api.fltr.com/v1
All API requests must be made over HTTPS. HTTP requests will be redirected to HTTPS.

​
Authentication

FLTR supports three authentication methods:
MethodHeader FormatRate Limit
API KeyAuthorization: Bearer fltr_sk_...1,000/hour
OAuth TokenAuthorization: Bearer fltr_at_...15,000/hour
SessionCookie-based15,000/hour

Authentication Guide

Learn how to authenticate with FLTR →

​
Request Format

​
JSON Bodies

All POST, PUT, and PATCH requests should include Content-Type: application/json header with a JSON body: 
curl -X POST https://api.fltr.com/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dataset",
    "description": "A test dataset"
  }'

​
File Uploads

For file uploads, use multipart/form-data: 
curl -X POST https://api.fltr.com/v1/datasets/ds_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'metadata={"title":"Document"}'

​
Response Format

​
Success Responses

Successful requests return JSON with appropriate HTTP status codes: 
{
  "id": "ds_abc123",
  "name": "My Dataset",
  "created_at": "2024-01-10T12:00:00Z"
}
Common Success Codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded with no response body

​
Error Responses

Errors return JSON with an error message and code: 
{
  "error": "Dataset not found",
  "code": "dataset_not_found",
  "details": {
    "dataset_id": "ds_invalid"
  }
}
Common Error Codes:
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn’t exist
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

​
Rate Limiting

API requests are limited based on authentication method: 
Anonymous:     50 requests/hour
API Key:       1,000 requests/hour
OAuth/Session: 15,000 requests/hour

​
Rate Limit Headers

All responses include rate limit information: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704657600
  • X-RateLimit-Limit - Total requests allowed per hour
  • X-RateLimit-Remaining - Requests remaining in current window
  • X-RateLimit-Reset - Unix timestamp when limit resets

​
Rate Limit Exceeded

When you exceed the limit, you’ll receive a 429 response: 
{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "retry_after": 3600
}

Rate Limits Guide

Learn more about rate limiting →

​
Pagination

List endpoints support pagination using limit and offset parameters: 
GET /v1/datasets?limit=20&offset=40
Parameters:
  • limit - Number of items per page (default: 20, max: 100)
  • offset - Number of items to skip (default: 0)
Response: 
{
  "datasets": [...],
  "total": 156,
  "limit": 20,
  "offset": 40,
  "has_more": true
}

​
Idempotency

POST requests that create resources support idempotency keys to safely retry requests: 
curl -X POST https://api.fltr.com/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"name":"My Dataset"}'
Requests with the same idempotency key will return the same response, preventing duplicate resource creation.

​
Resource Types

​
Datasets

Containers for related documents.

Datasets API

Explore dataset endpoints →

​
Documents

Files and text content within datasets.

Documents API

Explore document endpoints →

​
MCP Endpoints

Model Context Protocol for semantic search.

MCP API

Explore MCP endpoints →

​
Webhooks

Event-driven notifications.

Webhooks API

Explore webhook endpoints →

Create Dataset

POST /v1/datasets

Upload Document

POST /v1/datasets/:id/documents

Query Dataset

POST /v1/mcp/query

List Datasets

GET /v1/datasets