Skip to main content

QuickAdd API

The QuickAdd API provides a powerful interface for automating tasks in Obsidian through scripts, macros, and inline scripts. The API offers methods for user interaction, file manipulation, AI integration, and more.

Accessing the API​

The API can be accessed in several ways:

From QuickAdd Scripts (Macros/User Scripts)​

module.exports = async (params) => {
const { quickAddApi, app, variables } = params;
// Use quickAddApi here
};

From Other Plugins/Scripts​

const quickAddApi = app.plugins.plugins.quickadd.api;
// Use the API methods

From Templater Scripts​

<%*
const quickAddApi = app.plugins.plugins.quickadd.api;
const result = await quickAddApi.inputPrompt("Enter value:");
tR += result;
%>

User Input Methods​

inputPrompt(header: string, placeholder?: string, value?: string): Promise<string>​

Opens a prompt that asks for text input.

Parameters:

  • header: The prompt title/question
  • placeholder: (Optional) Placeholder text in the input field
  • value: (Optional) Default value

Returns: Promise resolving to the entered string, or null if cancelled

Example:

const name = await quickAddApi.inputPrompt(
"What's your name?",
"Enter your full name",
"John Doe"
);

if (name) {
console.log(`Hello, ${name}!`);
}

wideInputPrompt(header: string, placeholder?: string, value?: string): Promise<string>​

Opens a wider prompt for longer text input (multi-line).

Parameters: Same as inputPrompt

Returns: Promise resolving to the entered string, or null if cancelled

Example:

const description = await quickAddApi.wideInputPrompt(
"Project Description",
"Enter a detailed description...",
"This project aims to..."
);

yesNoPrompt(header: string, text?: string): Promise<boolean>​

Opens a confirmation dialog with Yes/No buttons.

Parameters:

  • header: The dialog title
  • text: (Optional) Additional explanation text

Returns: Promise resolving to true (Yes) or false (No)

Example:

const confirmed = await quickAddApi.yesNoPrompt(
"Delete Note?",
"This action cannot be undone."
);

if (confirmed) {
// Proceed with deletion
}

infoDialog(header: string, text: string[] | string): Promise<void>​

Shows an information dialog with an OK button.

Parameters:

  • header: Dialog title
  • text: Single string or array of strings (for multiple lines)

Example:

await quickAddApi.infoDialog(
"Operation Complete",
[
"Files processed: 10",
"Errors: 0",
"Time taken: 2.5 seconds"
]
);

suggester(displayItems: string[] | Function, actualItems: string[]): Promise<string>​

Opens a selection prompt with searchable options.

Parameters:

  • displayItems: Array of display strings OR a map function
  • actualItems: Array of actual values to return

Returns: Promise resolving to the selected value, or null if cancelled

Examples:

Basic usage:

const fruit = await quickAddApi.suggester(
["🍎 Apple", "🍌 Banana", "🍊 Orange"],
["apple", "banana", "orange"]
);

With map function:

const files = app.vault.getMarkdownFiles();
const selectedFile = await quickAddApi.suggester(
file => file.basename, // Display just the filename
files // Return the full file object
);

Complex objects:

const tasks = [
{ id: 1, title: "Task 1", priority: "high" },
{ id: 2, title: "Task 2", priority: "low" }
];

const selectedTask = await quickAddApi.suggester(
task => `${task.title} (${task.priority})`,
tasks
);

checkboxPrompt(items: string[], selectedItems?: string[]): Promise<string[]>​

Opens a checkbox prompt allowing multiple selections.

Parameters:

  • items: Array of options to display
  • selectedItems: (Optional) Array of pre-selected items

Returns: Promise resolving to array of selected items

Example:

const features = await quickAddApi.checkboxPrompt(
["Dark Mode", "Auto-save", "Spell Check", "Line Numbers"],
["Auto-save", "Line Numbers"] // Pre-selected
);

console.log("Enabled features:", features);

Choice Execution​

executeChoice(choiceName: string, variables?: {[key: string]: any}): Promise<void>​

Executes another QuickAdd choice programmatically.

Parameters:

  • choiceName: Name of the choice to execute
  • variables: (Optional) Variables to pass to the choice

Example:

// Execute a template choice with variables
await quickAddApi.executeChoice("Create Meeting Note", {
meetingTitle: "Project Review",
attendees: "John, Jane, Bob",
date: "2024-01-15",
value: "Main agenda content" // Special: maps to {{VALUE}}
});

Batch processing example:

const contacts = [
{ name: "John Doe", email: "john@example.com", company: "ACME" },
{ name: "Jane Smith", email: "jane@example.com", company: "Tech Corp" }
];

for (const contact of contacts) {
await quickAddApi.executeChoice("Create Contact", {
contactName: contact.name,
contactEmail: contact.email,
contactCompany: contact.company
});
}

Utility Module​

Access via quickAddApi.utility:

getClipboard(): Promise<string>​

Gets the current clipboard contents.

Example:

const clipboardText = await quickAddApi.utility.getClipboard();
console.log("Clipboard contains:", clipboardText);

setClipboard(text: string): Promise<void>​

Sets the clipboard contents.

Example:

await quickAddApi.utility.setClipboard("Hello, World!");

Combined example:

// Transform clipboard contents
const original = await quickAddApi.utility.getClipboard();
const transformed = original.toUpperCase();
await quickAddApi.utility.setClipboard(transformed);

Date Module​

Access via quickAddApi.date:

now(format?: string, offset?: number): string​

Gets formatted current date/time.

Parameters:

  • format: (Optional) Moment.js format string, defaults to "YYYY-MM-DD"
  • offset: (Optional) Day offset (negative for past, positive for future)

Examples:

// Current date
const today = quickAddApi.date.now(); // "2024-01-15"

// Custom format
const timestamp = quickAddApi.date.now("YYYY-MM-DD HH:mm:ss");

// With offset
const nextWeek = quickAddApi.date.now("YYYY-MM-DD", 7);
const lastMonth = quickAddApi.date.now("YYYY-MM-DD", -30);

tomorrow(format?: string): string​

Shorthand for now(format, 1).

yesterday(format?: string): string​

Shorthand for now(format, -1).

Example:

const yesterdayLog = `Daily Notes/${quickAddApi.date.yesterday()}.md`;
const tomorrowTask = `Tasks for ${quickAddApi.date.tomorrow("dddd, MMMM D")}`;

AI Module​

Access via quickAddApi.ai:

prompt(prompt: string, model: string, settings?: object): Promise<object>​

Sends a prompt to an AI model and returns the response.

Parameters:

  • prompt: The prompt text
  • model: Model name (e.g., "gpt-4", "gpt-3.5-turbo")
  • settings: (Optional) Configuration object:
    • variableName: Output variable name (default: "output")
    • shouldAssignVariables: Auto-assign to variables (default: false)
    • modelOptions: Model parameters (temperature, max_tokens, etc.)
    • showAssistantMessages: Show AI responses in UI (default: true)
    • systemPrompt: Override system prompt

Returns: Object with:

  • [variableName]: The AI response
  • [variableName]-quoted: The response in markdown quote format

Example:

const result = await quickAddApi.ai.prompt(
"Summarize this text: " + noteContent,
"gpt-4",
{
variableName: "summary",
modelOptions: {
temperature: 0.3,
max_tokens: 150
}
}
);

console.log(result.summary);
// Use in template: {{VALUE:summary}}

getModels(): string[]​

Returns available AI models.

Example:

const models = quickAddApi.ai.getModels();
const selectedModel = await quickAddApi.suggester(models, models);

getMaxTokens(model: string): number​

Gets the maximum token limit for a model.

countTokens(text: string, model: string): number​

Counts tokens in text according to model's tokenization.

Example:

const text = await quickAddApi.utility.getClipboard();
const tokenCount = quickAddApi.ai.countTokens(text, "gpt-4");

if (tokenCount > 4000) {
await quickAddApi.infoDialog(
"Text Too Long",
`The text contains ${tokenCount} tokens, which exceeds the model limit.`
);
}

Complete Example: Research Assistant​

Here's a comprehensive example combining multiple API features:

module.exports = async (params) => {
const { quickAddApi, app, variables } = params;

try {
// Get research parameters
const topic = await quickAddApi.inputPrompt("Research Topic:");
if (!topic) return;

const sources = await quickAddApi.checkboxPrompt(
["Web Search", "Academic Papers", "Books", "Videos"],
["Web Search", "Academic Papers"]
);

// AI-assisted outline generation
const { outline } = await quickAddApi.ai.prompt(
`Create a research outline for: ${topic}`,
"gpt-4",
{
variableName: "outline",
shouldAssignVariables: true,
modelOptions: { temperature: 0.7 }
}
);

// Create folder structure
const folder = `Research/${topic}`;

// Check if folder exists before creating
try {
const folderExists = await app.vault.adapter.exists(folder);
if (!folderExists) {
await app.vault.createFolder(folder);
}
} catch (err) {
console.error(`Failed to create folder: ${err}`);
new Notice(`Failed to create research folder: ${err.message}`);
return;
}

// Set variables for templates
variables.topic = topic;
variables.sources = sources.join(", ");
variables.date = quickAddApi.date.now("YYYY-MM-DD HH:mm");
variables.outline = outline;

// Execute template choice
await quickAddApi.executeChoice("Research Template", variables);

// Show completion
await quickAddApi.infoDialog(
"Research Project Created",
[
`Topic: ${topic}`,
`Sources: ${sources.length} selected`,
`Location: ${folder}`,
"AI outline generated successfully"
]
);

} catch (error) {
console.error("Research assistant error:", error);
new Notice(`Error: ${error.message}`);
}
};

Error Handling Best Practices​

Always wrap API calls in try-catch blocks:

module.exports = async (params) => {
const { quickAddApi } = params;

try {
const input = await quickAddApi.inputPrompt("Enter value:");

if (!input) {
// User cancelled - handle gracefully
return;
}

// Process input...

} catch (error) {
console.error("Script error:", error);

await quickAddApi.infoDialog(
"Error",
`An error occurred: ${error.message}`
);
}
};

Performance Tips​

  1. Batch Operations: Use loops wisely to avoid overwhelming the system
  2. Debounce User Input: Add delays between rapid operations
  3. Check File Existence: Verify files exist before operations
  4. Validate Input: Always validate user input before processing

See Also​