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:

Method	Header Format	Rate Limit
API Key	`Authorization: Bearer fltr_sk_...`	1,000/hour
OAuth Token	`Authorization: Bearer fltr_at_...`	15,000/hour
Session	Cookie-based	15,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 →

Quick Links

Create Dataset

POST /v1/datasets

Upload Document

POST /v1/datasets/:id/documents

Query Dataset

POST /v1/mcp/query

List Datasets

GET /v1/datasets

​API Reference

​Base URL

​Authentication

Authentication Guide

​Request Format

​JSON Bodies

​File Uploads

​Response Format

​Success Responses

​Error Responses

​Rate Limiting

​Rate Limit Headers

​Rate Limit Exceeded