Documentation Index
Fetch the complete documentation index at: https://mintlify.com/seyarhasir/AiVault/llms.txt
Use this file to discover all available pages before exploring further.
Introduction
AiVault uses Convex as its backend platform. Convex provides real-time queries and mutations that are type-safe and automatically reactive.
API Structure
The AiVault API is organized into three main modules:
- Tools API - Core functionality for managing AI tools
- Bookmarks API - User bookmark management
- Reviews API - User reviews and ratings
Queries vs Mutations
Queries
Queries are read-only operations that fetch data. They are:
- Automatically cached and reactive
- Re-executed when underlying data changes
- Cannot modify database state
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
function MyComponent() {
const tools = useQuery(api.tools.getTools, {
category: "Chatbots",
sort: "upvotes"
});
return <div>{tools?.map(tool => tool.name)}</div>;
}
Mutations
Mutations are write operations that modify data. They:
- Can insert, update, or delete records
- Return values immediately
- Trigger reactive updates to queries
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
function MyComponent() {
const submitTool = useMutation(api.tools.submitTool);
const handleSubmit = async () => {
await submitTool({
name: "My AI Tool",
description: "An amazing AI tool",
category: "Chatbots",
tags: ["ai", "chat"],
websiteUrl: "https://example.com",
pricing: "Free"
});
};
return <button onClick={handleSubmit}>Submit Tool</button>;
}
Authentication Requirements
Most API operations require authentication through Clerk:
-
Public queries - No authentication required:
getToolsgetToolBySluggetToolByIdgetRelatedToolsgetFeaturedToolsgetStats
-
Authenticated operations - User must be signed in:
getSubmittedToolssubmitToolupvoteToolgetBookmarkstoggleBookmarkisBookmarkedaddReview
-
Admin-only operations - Requires admin user ID:
getPendingToolsapproveToolrejectToolgetAdminStats
Authentication errors throw:
Error: "Unauthenticated" - User not signed in
Error: "Unauthorized: Admin access required" - Non-admin user
Error Handling
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
function MyComponent() {
const submitTool = useMutation(api.tools.submitTool);
const handleSubmit = async () => {
try {
await submitTool({ /* ... */ });
} catch (error) {
if (error.message === "Unauthenticated") {
// Redirect to sign in
}
}
};
}
Calling from Server Components
For Next.js Server Components, use Convex’s server-side API:
import { ConvexHttpClient } from "convex/browser";
import { api } from "../convex/_generated/api";
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
export default async function Page() {
const tools = await convex.query(api.tools.getTools, {
category: "Chatbots"
});
return <div>{tools.map(tool => tool.name)}</div>;
}
Real-Time Updates
Convex queries automatically update when data changes:
function ToolsList() {
// This component will automatically re-render when tools change
const tools = useQuery(api.tools.getTools, {});
return (
<div>
{tools?.map(tool => (
<ToolCard key={tool._id} tool={tool} />
))}
</div>
);
}
Next Steps
Tools API
Manage AI tools, submissions, and approvals
Bookmarks API
User bookmarking functionality
Reviews API
User reviews and ratings