Skip to main content

​
createCard

Creates a new card in Teak. The card type can be auto-detected based on content, or explicitly specified. All cards go through an AI processing pipeline for metadata extraction, categorization, and enhancement. 
import { useMutation } from "convex/react";
import { api } from "@teak/convex";

function AddCardForm() {
  const createCard = useMutation(api.card.createCard.createCard);

  const handleSubmit = async (content: string) => {
    const cardId = await createCard({
      content,
      type: "text",
      tags: ["important"],
      notes: "Quick note about this card"
    });
    console.log("Created card:", cardId);
  };

  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

​
Arguments

​
content
string
required
The main content of the card. For text cards, this is the primary text. For links, this can include the URL or description. For quotes, quotation marks are automatically normalized.
​
type
CardType
The type of card to create. If omitted, Teak will automatically detect the type based on content analysis.Supported types:
  • text - Plain text notes
  • link - Web links with automatic metadata extraction
  • image - Image files with AI vision analysis
  • video - Video files with thumbnail generation
  • audio - Audio recordings with transcription
  • document - PDF and document files
  • palette - Color palettes with hex codes
  • quote - Quoted text with automatic formatting
​
url
string
URL associated with the card. Automatically extracted from content if not provided. Required for link cards to enable metadata extraction.
​
fileId
Id<'_storage'>
Storage ID of the uploaded file. Use ctx.storage.store() to upload files first, then pass the returned ID here.Required for: image, video, audio, document card types.
​
thumbnailId
Id<'_storage'>
Storage ID of a custom thumbnail image. If not provided, thumbnails are auto-generated for supported media types.
​
tags
string[]
User-defined tags for organizing and filtering cards. These are separate from AI-generated tags.
tags: ["work", "urgent", "design-system"]
​
notes
string
Additional notes or context about the card. Searchable and indexed separately from main content.
​
metadata
any
Custom metadata object. File-related fields (fileName, fileSize, mimeType, duration, width, height) are automatically extracted to fileMetadata.
metadata: {
  source: "mobile-app",
  importedFrom: "notion"
}
​
colors
Color[]
Array of color objects for palette cards. If creating a palette card without colors, Teak will attempt to extract colors from the content, notes, or tags.

​
Returns

​
cardId
Id<'cards'>
The unique identifier of the newly created card. Use this to query the card or perform updates.
const cardId = await createCard({ content: "Hello" });
// Returns: "jd7x2k8p9q5r6s7t8u9v0w1x2y3z4"

​
Behavior

When type is not provided, Teak uses the following rules:
  1. Quote detection: If content contains quotation marks that are removed during normalization, type is set to "quote"
  2. URL extraction: URLs are automatically extracted from content and set in the url field
  3. Default fallback: If no specific type is detected, defaults to "text"
  4. Classification pipeline: Auto-detected cards enter the classification stage for AI-based type detection
After creation, cards automatically enter a multi-stage processing workflow:
  1. Classification (if type auto-detected)
    • AI determines the most appropriate card type
    • Extracts palette colors for visual content
  2. Categorization (for link cards)
    • Waits for metadata extraction to complete
    • Assigns category based on link content
  3. Metadata Extraction
    • Links: Fetches page title, description, preview images
    • Media: Generates AI tags and summaries
    • Audio: Creates transcripts
  4. Renderables Generation
    • Creates thumbnails for images and videos
    • Skips if original file is already small
The ensureCardCreationAllowed() function checks:
  • User authentication
  • Rate limits (prevents spam)
  • Card count limits (subscription-based)
Throws an error if limits are exceeded.
For quote cards, content is automatically normalized:
  • Removes leading/trailing quotation marks
  • Preserves internal quotes
  • Stores normalized version in database
// Input
content: '"This is a quote" - Author'

// Stored as
content: 'This is a quote - Author'
type: 'quote'
When creating a palette card without explicit colors:
  1. Combines content, notes, and tags into analysis text
  2. Extracts up to 12 colors using extractPaletteColors()
  3. Builds color facets (hex codes and hue categories)
  4. Enables color-based search and filtering

​
Error Handling

​
User must be authenticated
Error
Thrown when no authenticated user session is found.
throw new Error("User must be authenticated");
​
Rate limit exceeded
Error
Thrown by ensureCardCreationAllowed() when rate limits are hit.
​
Card count limit exceeded
Error
Thrown when user has reached their subscription’s card limit.

​
Source Reference

Implemented in packages/convex/card/createCard.ts:192

Build docs developers (and LLMs) love

Get started for freeTalk to us