Help & FAQ

FileVault is a storage API for AI agents. Each agent gets an isolated namespace with file storage, semantic search, and persistent memory — all accessible via a single REST API or TypeScript SDK.

Send a POST request to /api/v1/agents with a name field. You'll receive a secret API key (fv_sk_...) once — store it immediately. All subsequent requests authenticate with this key via the Authorization: Bearer header.

Pass your agent key in every request header: Authorization: Bearer fv_sk_your_key_here. Requests without a valid key return 401 Unauthorized.

Yes. Import the FileVault class from the SDK, pass your API key, and get fully typed methods for every endpoint — upload, search, memory, collections, webhooks, and more. No raw fetch required.

POST to /api/v1/files with a multipart form containing the file field. Add index=true to automatically extract and embed the file content for semantic search. You can also attach arbitrary JSON metadata.

POST to /api/v1/files/batch with up to 10 files in a files[] field. The response includes a result entry per file, with partial success (207) if some files fail.

Each file can be up to 50 MB. Per-agent limits are 1,000 files and 1 GB total storage on the free tier.

GET /api/v1/files/:id returns metadata and a download URL. DELETE /api/v1/files/:id removes the file and all associated embeddings from storage.

All file types are stored. For indexing and semantic search, FileVault extracts text from HTML, plain text, PDF, and JSON files. Other types are stored and downloadable but not searchable.

When you upload with index=true (or call POST /api/v1/files/:id/index later), FileVault extracts text from the file, splits it into chunks, generates embeddings via OpenRouter, and stores them in a pgvector index.

POST to /api/v1/search with a query string. FileVault embeds your query and returns the most similar chunks ranked by cosine similarity. Filter by file_id, collection_id, metadata fields, or include shared agent content with include_shared=true.

Pass file_id or collection_id in the search request body to scope results. You can combine filters — e.g. search within a collection while filtering by a metadata tag.

Memory lets your agent store arbitrary text snippets with an embedding attached — conversation turns, extracted facts, decisions, or any knowledge it wants to recall later. Each memory can optionally expire.

POST to /api/v1/memory with a content string (and optional expiresAt). GET /api/v1/memory returns a paginated list. Memories are also included in semantic search results — use type=memory in the search request to search only memories.

Up to 5,000 active memories on the free tier. Expired memories don't count toward the limit.

Collections are named groups of files within your agent's namespace. Use them to organise files by project, topic, or workflow — and to scope searches to a specific subset of your storage.

POST to /api/v1/shares with another agent's agent_id to grant it read access to your files and embeddings. The grantee can then include your content in searches using include_shared=true.

FileVault fires a webhook on file.created after every successful upload. The payload includes file_id, name, size_bytes, and is_indexed.

PUT to /api/v1/webhooks with a url field. FileVault will POST events to that URL as they happen. Use DELETE /api/v1/webhooks to remove it.

Check that your Authorization header is exactly: Bearer fv_sk_your_key. The key is shown only once at agent creation — if you lost it, create a new agent.

The file must be indexed first. Either upload with index=true, or call POST /api/v1/files/:id/index after the fact. Check the index_status field on the file — it will be pending, indexed, or failed.

The free tier allows 20 uploads per minute per agent. If you hit the limit, the API returns 429 with a Retry-After header. Batch uploads (/api/v1/files/batch) count as one request for up to 10 files.

GET /api/v1/usage returns your current file count, indexed file count, storage bytes used, and memory count — all in a single call.