Skip to main content

​
Overview

The Tools API provides all functionality for managing AI tools in AiVault. It includes queries for fetching tools with various filters, mutations for submitting and moderating tools, and statistics endpoints.

​
Queries

​
getTools

Fetch a filtered and sorted list of approved tools. Source: /home/daytona/workspace/source/convex/tools.ts:28
​
category
string
Filter by category (e.g., “Chatbots”, “Image Generation”). Use “All” to skip filtering.
​
pricing
string
Filter by pricing model: “Free”, “Freemium”, or “Paid”. Use “All” to skip filtering.
​
search
string
Search query to match against tool name, description, or tags (case-insensitive).
​
sort
string
Sort order: “newest” (default) or “upvotes”
​
tools
Tool[]
Array of approved tools matching the filters
const tools = useQuery(api.tools.getTools, {
  category: "Chatbots",
  pricing: "Free",
  search: "gpt",
  sort: "upvotes"
});

​
getToolBySlug

Fetch a single tool by its URL slug. Source: /home/daytona/workspace/source/convex/tools.ts:86
​
slug
string
required
URL-friendly tool identifier
​
tool
Tool | null
Tool object if found, null otherwise
const tool = useQuery(api.tools.getToolBySlug, {
  slug: "chatgpt"
});

​
getToolById

Fetch a single tool by its ID. Source: /home/daytona/workspace/source/convex/tools.ts:96
​
toolId
Id<'tools'>
required
Unique tool identifier
​
tool
Tool | null
Tool object if found, null otherwise
const tool = useQuery(api.tools.getToolById, {
  toolId: "jd7a8f9a8sd9f8a9sd8f9a" as Id<"tools">
});

​
getRelatedTools

Fetch related tools in the same category, sorted by upvotes. Source: /home/daytona/workspace/source/convex/tools.ts:103
​
category
string
required
Tool category to match
​
excludeSlug
string
required
Slug of tool to exclude from results (typically the current tool)
​
tools
Tool[]
Up to 4 approved related tools, sorted by upvotes
const relatedTools = useQuery(api.tools.getRelatedTools, {
  category: "Chatbots",
  excludeSlug: "chatgpt"
});

​
getFeaturedTools

Fetch all featured tools. Source: /home/daytona/workspace/source/convex/tools.ts:118 Parameters: None
​
tools
Tool[]
Array of featured tools, sorted by creation date (newest first)
const featuredTools = useQuery(api.tools.getFeaturedTools, {});

​
getSubmittedTools

Fetch all tools submitted by the authenticated user. Source: /home/daytona/workspace/source/convex/tools.ts:128 Authentication: Required Parameters: None
​
tools
Tool[]
Array of tools submitted by the current user (both approved and pending)
const myTools = useQuery(api.tools.getSubmittedTools, {});

​
getPendingTools

Fetch all tools pending approval. Source: /home/daytona/workspace/source/convex/tools.ts:139 Authentication: Admin required Parameters: None
​
tools
Tool[]
Array of unapproved tools
const pendingTools = useQuery(api.tools.getPendingTools, {});

​
getStats

Fetch public platform statistics. Source: /home/daytona/workspace/source/convex/tools.ts:234 Parameters: None
​
stats
object
Platform statistics
const stats = useQuery(api.tools.getStats, {});
// Returns: { totalTools: 150, totalCategories: 12, totalFeatured: 8, totalUpvotes: 3420 }

​
getAdminStats

Fetch detailed statistics including pending tools. Source: /home/daytona/workspace/source/convex/tools.ts:254 Authentication: Admin required Parameters: None
​
stats
object
Detailed platform statistics
const adminStats = useQuery(api.tools.getAdminStats, {});

​
Mutations

​
submitTool

Submit a new tool for approval. Source: /home/daytona/workspace/source/convex/tools.ts:149 Authentication: Required
​
name
string
required
Tool name
​
description
string
required
Short description (1-2 sentences)
​
longDescription
string
Detailed description
​
category
string
required
Tool category (e.g., “Chatbots”, “Image Generation”)
​
tags
string[]
required
Array of tags
​
websiteUrl
string
required
Tool website URL
​
logoUrl
string
Tool logo URL
​
pricing
string
required
Pricing model: “Free”, “Freemium”, or “Paid”
​
pricingDetails
string
Detailed pricing information (e.g., “Free tier available. Pro from $20/mo”)
​
features
string[]
Array of features
​
useCases
string[]
Array of use cases
​
pros
string[]
Array of pros
​
cons
string[]
Array of cons
​
platforms
string[]
Supported platforms (“Web”, “iOS”, “Android”, “Desktop”, “API”, “Chrome Extension”)
​
twitterUrl
string
Twitter profile URL
​
githubUrl
string
GitHub repository URL
​
discordUrl
string
Discord server URL
​
result
object
Submission result
const submitTool = useMutation(api.tools.submitTool);

const result = await submitTool({
  name: "My AI Tool",
  description: "An amazing AI tool for developers",
  longDescription: "This tool helps developers build AI applications faster...",
  category: "Development",
  tags: ["ai", "development", "automation"],
  websiteUrl: "https://myaitool.com",
  logoUrl: "https://myaitool.com/logo.png",
  pricing: "Freemium",
  pricingDetails: "Free tier available. Pro from $29/mo",
  features: [
    "Real-time code generation",
    "API integration",
    "Team collaboration"
  ],
  useCases: [
    "Building web applications",
    "Automating repetitive tasks"
  ],
  pros: ["Fast", "Easy to use", "Great documentation"],
  cons: ["Limited free tier"],
  platforms: ["Web", "API"],
  twitterUrl: "https://twitter.com/myaitool",
  githubUrl: "https://github.com/myaitool"
});

// Returns: { toolId: "...", slug: "my-ai-tool" }
Notes:
  • Slug is automatically generated from the name
  • If slug already exists, timestamp is appended
  • Tool starts with approved: false (requires admin approval)
  • Tool is marked with isNew: true
  • Initial upvotes set to 0

​
approveTool

Approve a pending tool submission. Source: /home/daytona/workspace/source/convex/tools.ts:207 Authentication: Admin required
​
toolId
Id<'tools'>
required
ID of the tool to approve
​
sendEmail
boolean
Whether to send approval email to submitter (not yet implemented)
​
result
object
​
success
boolean
Always true on success
const approveTool = useMutation(api.tools.approveTool);

await approveTool({
  toolId: "jd7a8f9a8sd9f8a9sd8f9a" as Id<"tools">,
  sendEmail: true
});

​
rejectTool

Reject and delete a pending tool submission. Source: /home/daytona/workspace/source/convex/tools.ts:219 Authentication: Admin required
​
toolId
Id<'tools'>
required
ID of the tool to reject
​
reason
string
Rejection reason to send to submitter
​
sendEmail
boolean
Whether to send rejection email to submitter (not yet implemented)
​
result
object
const rejectTool = useMutation(api.tools.rejectTool);

await rejectTool({
  toolId: "jd7a8f9a8sd9f8a9sd8f9a" as Id<"tools">,
  reason: "Duplicate submission",
  sendEmail: true
});

​
upvoteTool

Increment the upvote count for a tool. Source: /home/daytona/workspace/source/convex/tools.ts:284
​
toolId
Id<'tools'>
required
ID of the tool to upvote
Returns: void Errors:
  • "Tool not found" - If toolId doesn’t exist
const upvoteTool = useMutation(api.tools.upvoteTool);

await upvoteTool({
  toolId: tool._id
});
Note: This mutation does not prevent duplicate upvotes from the same user. You may want to implement client-side tracking to prevent multiple upvotes.

Build docs developers (and LLMs) love

Get started for freeTalk to us