QuickAdd

https://quickadd.obsidian.guide/docs
Admin
QuickAdd is an Obsidian community plugin that enhances workflow automation by allowing users to...
Tokens:28,949
Snippets:137
Trust Score:5.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Research Assistant Example

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

A complete example demonstrating how to use the QuickAdd API to create a research assistant. This includes taking user input for topic and sources, generating an AI-assisted outline, creating a folder structure, setting variables, executing a template, and providing user feedback.

```APIDOC
## Research Assistant Example

This example showcases a full workflow for a research assistant, integrating multiple QuickAdd API features to streamline the research process.

### Workflow

1.  **Input Prompt**: Asks the user for the research topic.
2.  **Checkbox Prompt**: Allows selection of research sources (Web Search, Academic Papers, Books, Videos).
3.  **AI Outline Generation**: Uses `quickAddApi.ai.prompt` to generate a research outline based on the topic.
4.  **Folder Creation**: Creates a new folder in the vault for the research project, checking for existence first.
5.  **Variable Assignment**: Sets variables (`topic`, `sources`, `date`, `outline`) for use in templates.
6.  **Template Execution**: Executes a pre-defined 'Research Template' with the assigned variables.
7.  **Info Dialog**: Displays a success message summarizing the created research project.

### Error Handling

Includes try-catch blocks to handle potential errors during folder creation and general script execution, providing user feedback via `Notice` and `infoDialog`.
```

--------------------------------

### Research Assistant Example with QuickAdd API

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

A complete example demonstrating the use of QuickAdd API for creating a research assistant. It includes user input prompts, AI-powered outline generation, folder creation, variable assignment, and template execution. It requires the quickAddApi and app objects from the parameters.

```javascript
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}`);  
    }  
};  
```

--------------------------------

### Accessing and Interacting with Other Obsidian Plugins via JavaScript

Source: https://quickadd.obsidian.guide/docs/Choices/MacroChoice

Shows how to access other installed Obsidian plugins from within a user script. It provides examples for accessing the Templater and MetaEdit plugins and demonstrates how to use their respective APIs if they are available.

```javascript
module.exports = async (params) => {
    const { app } = params;
      
    // Access Templater
    const templater = app.plugins.plugins["templater-obsidian"];
    if (templater) {
        // Use Templater API
    }
      
    // Access MetaEdit
    const metaedit = app.plugins.plugins["metaedit"];
    if (metaedit) {
        const { update } = metaedit.api;
        await update("property", "value", "path/to/file.md");
    }
};
```

--------------------------------

### AI Assistant Summarizer Prompt Template

Source: https://quickadd.obsidian.guide/docs/AIAssistant

A prompt template for the AI Assistant to summarize selected text. It instructs the AI to use only the provided text, maintain brevity, and present the summary in an outline form. The {{value}} placeholder is expected to be replaced with the selected text.

```text
Please summarize the following text. Use only the text itself as material for summarization, and do not add anything new. Rewrite this for brevity, in outline form:  
{{value}}  

```

--------------------------------

### Configure Gemini Google AI Provider in QuickAdd

Source: https://quickadd.obsidian.guide/docs/AIAssistant

This configuration sets up the Gemini provider from Google AI in QuickAdd. It includes the provider name, URL, and requires an AI Studio API key. Users can specify one or more supported Gemini models and their maximum token limits. Ensure 'Disable AI & Online features' is off in QuickAdd settings for requests to function.

```plaintext
Name: Gemini
URL: https://generativelanguage.googleapis.com
API Key: (AI Studio API key)
Models (add one or more):
  - gemini-1.5-pro (Max Tokens: 1000000)
  - gemini-1.5-flash (Max Tokens: 1000000)
  - gemini-1.5-flash-8b (Max Tokens: 1000000)
```

--------------------------------

### Dynamic Suggester Options with Dataview and QuickAdd (JavaScript)

Source: https://quickadd.obsidian.guide/docs/Advanced/onePageInputs

This example shows how to dynamically populate the options for a suggester input field using data retrieved from the Dataview plugin. It fetches project names from notes with a 'project' type and uses them as options for the project selection input.

```javascript
export default async function entry({ quickAddApi, app }) {
  // Get dynamic options from Dataview
  const dv = app.plugins.plugins.dataview?.api;
  const projectNames = dv?.pages()
    .where(p => p.type === "project")
    .map(p => p.file.name)
    .array() ?? ["Inbox"];

  const values = await quickAddApi.requestInputs([
    {
      id: "project",
      label: "Select Project",
      type: "suggester",
      options: projectNames,
      placeholder: "Start typing project name..."
    },
  ]);

  const { project } = values;
}
```

--------------------------------

### Accessing the QuickAdd API

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Demonstrates how to access the QuickAdd API from different scripting environments within Obsidian.

```APIDOC
## Accessing the QuickAdd API

### From QuickAdd Scripts (Macros/User Scripts)

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

### From Other Plugins/Scripts

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

### From Templater Scripts

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

--------------------------------

### Insert After Example with Daily Journal

Source: https://quickadd.obsidian.guide/docs/Choices/CaptureChoice

Shows how to use the 'Insert After' functionality to add captured text after a specific heading in a daily journal. This example targets the '## What did I do today?' heading.

```markdown
## What did I do today?
```

--------------------------------

### Dynamic Daily Journal Filename Example

Source: https://quickadd.obsidian.guide/docs/Choices/CaptureChoice

An example of using format syntax for dynamic file naming in QuickAdd. This configuration automatically creates or selects a daily journal file based on the current date and day of the week.

```markdown
bins/daily/{{DATE:gggg-MM-DD - ddd MMM D}}.md
```

--------------------------------

### Performance Tips

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Provides essential performance optimization tips for QuickAdd scripts, focusing on efficiency and avoiding common pitfalls.

```APIDOC
## Performance Tips

Optimize your QuickAdd scripts for better performance and user experience by following these guidelines:

1.  **Batch Operations**: Process multiple items efficiently, potentially in batches, to avoid redundant operations.
2.  **Debounce User Input**: Implement delays or debouncing mechanisms for rapid user inputs to prevent overwhelming the system.
3.  **Check File Existence**: Before performing file operations (create, delete, modify), verify if the file or folder already exists to avoid unnecessary errors or operations.
4.  **Validate Input**: Ensure all user-provided input is validated before processing to prevent unexpected behavior or errors.
```

--------------------------------

### QuickAdd Global Variable Syntax and Usage Example

Source: https://quickadd.obsidian.guide/docs/GlobalVariables

Demonstrates the syntax for defining and using global variables within QuickAdd. Global variables allow for vault-scoped, reusable snippets that can be referenced in file names, folder paths, and template content. The example shows how a global variable 'MyProjects' is defined with a list of projects and then used in both a file path and template content.

```markdown
Name: MyProjects  
Value: {{VALUE:Inbox,Work,Personal,Archive}}  
  
In a template path:  
Projects/{{GLOBAL_VAR:MyProjects}}/{{DATE:YYYY}}/  
  
In content:  
- Project: {{GLOBAL_VAR:MyProjects}}  
- Created: {{DATE:YYYY-MM-DD}}  
```

--------------------------------

### Utility Module - Get Clipboard

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Provides access to utility functions, including a method to retrieve the current content of the system clipboard.

```APIDOC
## GET /api/utility/clipboard

### Description
Retrieves the current content stored in the system clipboard.

### Method
GET

### Endpoint
/api/utility/clipboard

### Parameters
None

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **clipboardContent** (string) - The text content currently in the clipboard.

#### Response Example
```json
{
  "clipboardContent": "Text from clipboard"
}
```
```

--------------------------------

### Exporting Multiple Functions in QuickAdd Macros

Source: https://quickadd.obsidian.guide/docs/Choices/MacroChoice

Shows how a single QuickAdd script can export multiple functions, providing users with choices for execution. It includes a 'start' function that presents a suggester to choose between available options.

```javascript
module.exports = {  
    option1: async (params) => {  
        console.log("Running option 1");  
    },  
      
    option2: async (params) => {  
        console.log("Running option 2");  
    },  
      
    // Can also include variables  
    defaultValue: "some default",  
      
    // Main entry point  
    start: async (params) => {  
        const { quickAddApi } = params;  
        const choice = await quickAddApi.suggester(  
            ["Run Option 1", "Run Option 2"],  
            ["option1", "option2"]  
        );  
          
        if (choice === "option1") {  
            await module.exports.option1(params);  
        } else if (choice === "option2") {  
            await module.exports.option2(params);  
        }  
    }  
};

```

--------------------------------

### Capture to Tagged File Example

Source: https://quickadd.obsidian.guide/docs/Choices/CaptureChoice

Demonstrates capturing input to a file that has a specific tag. QuickAdd will prompt for a file containing the specified tag.

```markdown
#people
```

--------------------------------

### Logging Books to Daily Notes with QuickAdd and MetaEdit

Source: https://quickadd.obsidian.guide/docs/Choices/MacroChoice

An example QuickAdd macro that prompts the user for a book name and then uses the MetaEdit plugin's API to update the current day's note with the book title.

```javascript
module.exports = async (params) => {  
    const { quickAddApi: { inputPrompt }, app } = params;  
      
    // Get book name from user  
    const bookName = await inputPrompt("📖 Book Name");  
      
    // Get MetaEdit plugin  
    const { update } = app.plugins.plugins["metaedit"].api;  
      
    // Format today's date  
    const date = window.moment().format("YYYY-MM-DD");  
      
    // Update the daily note  
    await update("Book", bookName, `Daily Notes/${date}.md`);  
};

```

--------------------------------

### User Input Methods - inputPrompt

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

The `inputPrompt` method displays a modal for single-line text input from the user.

```APIDOC
### `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:**
```javascript
const name = await quickAddApi.inputPrompt(
    "What's your name?",
    "Enter your full name",
    "John Doe"
);

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

--------------------------------

### Capture to Folder and Create File Example

Source: https://quickadd.obsidian.guide/docs/Choices/CaptureChoice

Illustrates capturing input to a specific folder and creating a new file within that folder if it doesn't exist. This relies on the 'Create file if it doesn't exist' setting being enabled.

```markdown
CRM/people
```

--------------------------------

### Access QuickAdd API in Obsidian Scripts (JavaScript)

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Demonstrates how to access the QuickAdd API from within Obsidian scripts, such as macros or user scripts. It assumes the QuickAdd plugin is installed and enabled.

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

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

--------------------------------

### Get Available AI Models with QuickAdd API

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Retrieves a list of all AI models configured and available within the QuickAdd settings. This is useful for dynamically populating selection menus or for debugging.

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

--------------------------------

### Default Capture Format Example

Source: https://quickadd.obsidian.guide/docs/Choices/CaptureChoice

Demonstrates the default capture format in QuickAdd, which simply inserts the value entered by the user. This is the behavior when no custom format is specified.

```text
{{VALUE}}
```

--------------------------------

### API GET Request Utility (JavaScript)

Source: https://quickadd.obsidian.guide/docs/Examples/Template_AutomaticBookNotesFromReadwise

A generic utility function to perform authenticated GET requests to a specified URL. It appends query parameters if provided and includes necessary headers like 'Content-Type' and 'Authorization'. It returns the JSON response from the fetch call.

```javascript
async function apiGet(url, data) {
	let finalURL = new URL(url);
	if (data)
		Object.keys(data).forEach((key) =>
			finalURL.searchParams.append(key, data[key])
		);

	return await fetch(finalURL, {
		method: "GET",
		cache: "no-cache",
		headers: {
			"Content-Type": "application/json",
			Authorization: `Token ${token}`,
		},
	}).then(async (res) => await res.json());
}
```

--------------------------------

### Error Handling Best Practices

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Demonstrates best practices for error handling when using the QuickAdd API, emphasizing the importance of try-catch blocks for robust script execution.

```APIDOC
## Error Handling Best Practices

Always wrap API calls in `try-catch` blocks to gracefully handle potential errors and provide informative feedback to the user.

### Key Practices

*   **`try...catch` Blocks**: Enclose asynchronous operations that might fail within a `try` block and handle any errors in the `catch` block.
*   **User Feedback**: Use `quickAddApi.infoDialog` or `Notice` to inform the user about errors that occur during script execution.
*   **Graceful Cancellation**: Check for user cancellations (e.g., when a prompt returns `null` or `undefined`) and handle these scenarios without throwing errors.
```

--------------------------------

### Configure Advanced Obsidian QuickAdd Script

Source: https://quickadd.obsidian.guide/docs/UserScripts

This JavaScript example demonstrates a complete configuration for an Obsidian QuickAdd script, including various option types like text, dropdown, toggle, and format. It shows how to access and use these settings within the script's execution function, including input validation and setting variables for template use.

```javascript
module.exports = {
    entry: start,
    settings: {
        name: "Advanced Script",
        author: "Your Name",
        options: {
            "API Key": {
                type: "text",
                defaultValue: "",
                placeholder: "sk-...",
                secret: true,
                description: "OpenAI API key"
            },
            "Model": {
                type: "dropdown",
                defaultValue: "gpt-3.5-turbo",
                options: ["gpt-3.5-turbo", "gpt-4", "gpt-4-turbo"],
                description: "AI model to use"
            },
            "Include Metadata": {
                type: "toggle",
                defaultValue: true,
                description: "Include file metadata in output"
            },
            "Output Template": {
                type: "format",
                defaultValue: "## {{DATE:YYYY-MM-DD}}\n{{VALUE:content}}",
                placeholder: "Template for output",
                description: "Format for the output"
            },
            "Max Results": {
                type: "text",
                defaultValue: "10",
                placeholder: "Number",
                description: "Maximum number of results"
            }
        }
    }
};

async function start(params, settings) {
    const { quickAddApi, app, variables } = params;

    // Access settings
    const apiKey = settings["API Key"];
    const model = settings["Model"];
    const includeMetadata = settings["Include Metadata"];
    const outputTemplate = settings["Output Template"];
    const maxResults = parseInt(settings["Max Results"]);

    // Validate inputs
    if (!apiKey) {
        new Notice("Please configure your API key in the script settings");
        throw new Error("API key not configured");
    }

    // Use QuickAdd API
    const query = await quickAddApi.inputPrompt("Enter your search query:");
    if (!query) return;

    // Your logic here...
    console.log(`Using model: ${model}`);
    console.log(`Max results: ${maxResults}`);

    if (includeMetadata) {
        // Include metadata logic
    }

    // Set variables for use in templates
    variables.model = model;
    variables.query = query;
    variables.resultCount = maxResults;
}
```

--------------------------------

### Open QuickAdd in Obsidian with AutoHotkey (ControlSend)

Source: https://quickadd.obsidian.guide/docs/Misc/AHK_OpenQuickAddFromDesktop

This AutoHotkey script activates the Obsidian window and sends a specific key combination (Ctrl+Alt+Shift+G) to open QuickAdd. It requires the AutoHotkey program to be installed and running. This method might be less reliable than using the Advanced URI.

```autohotkey
#SingleInstance, Force
SendMode Input
SetWorkingDir, %A_ScriptDir%
SetTitleMatchMode, RegEx

!^+g::
    WinActivate, i) Obsidian
    ControlSend,, {CtrlDown}{AltDown}{ShiftDown}G{CtrlUp}{CtrlUp}{ShiftUp}, i)Obsidian
Return

```

--------------------------------

### Configure Ollama Local LLM Provider in QuickAdd

Source: https://quickadd.obsidian.guide/docs/AIAssistant

This configuration sets up Ollama, a local LLM server, as a provider in QuickAdd. It specifies the name, URL, and API key (which is empty for Ollama). Users must also add the desired model, such as 'mistral'. This allows for private data processing and use of specific models without cloud dependency.

```plaintext
Name: Ollama
URL: http://localhost:11434/v1
Api Key: (empty)
```

--------------------------------

### Obsidian Book Finder Template

Source: https://quickadd.obsidian.guide/docs/Examples/Macro_BookFinder

An example Obsidian template using QuickAdd variables to insert book details such as poster, author, title, category, status, and description into a new note. It provides a structure for organizing book-related information within your vault.

```markdown
![poster]({{VALUE:Poster}})  
  
**Author**:: {{VALUE:authors}}  
**Title**:: {{VALUE:title}}  
**Category**::{{VALUE:categories}}  
**Status**:: 📥  
  
**Related Books**  
### Core Questions for Me  
  
### Actions  
  
### My Notes  
  
## Details  
{{VALUE:description}}  


```

--------------------------------

### QuickAdd URI with Vault and Variable - Example

Source: https://quickadd.obsidian.guide/docs/Advanced/ObsidianUri

This example demonstrates how to specify a target vault and pass a value to a QuickAdd choice variable using the URI. The 'vault' parameter selects the vault, and 'value-contents' passes data to a variable named 'contents'. Both vault name and content are URL encoded.

```plaintext
obsidian://quickadd?vault=My%20Vault&choice=Daily%20log&value-contents=Lorem%20ipsum.
```

--------------------------------

### Open QuickAdd in Obsidian with AutoHotkey (Advanced URI)

Source: https://quickadd.obsidian.guide/docs/Misc/AHK_OpenQuickAddFromDesktop

This AutoHotkey script utilizes the Obsidian Advanced URI plugin to open QuickAdd. It activates the Obsidian window and then runs an Obsidian URI command. This method is generally more reliable. Ensure the Obsidian Advanced URI plugin is installed and replace `<YOUR_VAULT_NAME>` with your vault's name.

```autohotkey
SendMode Input
SetWorkingDir, %A_ScriptDir%
SetTitleMatchMode, RegEx

!^+g::
    WinActivate, i) Obsidian

    Run "obsidian://advanced-uri?vault=<YOUR_VAULT_NAME>&commandname=QuickAdd: Run QuickAdd"
Return

```

--------------------------------

### Allow Custom Input with Tailored Rendering

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Configures the suggester to allow users to input new values while providing custom rendering that highlights whether an input is new or existing.

```APIDOC
## POST /api/suggestions/custom-input-render

### Description
Enables custom rendering within the suggester prompt, specifically designed to differentiate between existing and newly entered values when custom input is allowed.

### Method
POST

### Endpoint
/api/suggestions/custom-input-render

### Parameters
#### Request Body
- **values** (Array<string>) - Required - The list of predefined values for the suggester.
- **allowCustomInput** (boolean) - Required - Specifies whether custom input is permitted.
- **suggesterOptions** (Object) - Optional - Options for the suggester, including `renderItem`.
  - **renderItem** (Function) - Optional - A function that receives `value` and `el` to render a suggestion item, with logic to determine if the value is new.

### Request Example
```json
{
  "values": ["Inbox", "Roadmap", "Backlog"],
  "allowCustomInput": true,
  "suggesterOptions": {
    "renderItem": "(value, el) => { const isNew = !values.includes(value); ... custom rendering logic ... }"
  }
}
```

### Response
#### Success Response (200)
- **selectedItem** (string) - The selected or newly entered item.

#### Response Example
```json
{
  "selectedItem": "New Project"
}
```
```

--------------------------------

### Manual String Formatting in Obsidian Front Matter (Before)

Source: https://quickadd.obsidian.guide/docs/TemplatePropertyTypes

An example of how data was manually formatted as strings within Obsidian front matter before the introduction of QuickAdd's automatic property type formatting feature.

```yaml
authors: "John Doe, Jane Smith, Bob Wilson"  # Manual string formatting  
```

--------------------------------

### AI Module - prompt

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Sends a prompt to a configured AI model and returns the response. Supports various models and customizable settings.

```APIDOC
## AI Module - prompt

Access via `quickAddApi.ai`:

### `prompt(prompt: string, model: string | {name: string}, settings?: object): Promise<object>`

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

**Parameters:**
  * `prompt`: The prompt text
  * `model`: Model identifier - either a string (e.g., `"gpt-4"`) or object with name property (e.g., `{name: "gpt-4"}`). The model must be configured in Settings → QuickAdd → AI → Providers.
  * `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 using string:**
```javascript
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}}
```

**Example using Model object:**
```javascript
const result = await quickAddApi.ai.prompt(
    "What is the capital of France?",
    {name: "gpt-4"},
    {
        variableName: "capital",
        shouldAssignVariables: true,
        modelOptions: {
            temperature: 0.6,
            max_tokens: 60
        }
    }
);
```

**Note:** For newer models like `gpt-4o` or custom provider models, add them in Settings → QuickAdd → AI → Providers. Some providers support auto-sync to automatically update available models.
```

--------------------------------

### Custom Rendering with Suggester

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Demonstrates how to provide custom rendering for items in the suggester prompt to control their appearance, including adding visual elements like color dots and subtitles.

```APIDOC
## POST /api/suggestions/render

### Description
Provides custom rendering for items displayed in the QuickAdd suggester. This allows for advanced UI customization beyond the default text display.

### Method
POST

### Endpoint
/api/suggestions/render

### Parameters
#### Request Body
- **items** (Array<Object>) - Required - An array of items to be displayed in the suggester.
  - **name** (string) - Required - The display name of the item.
  - **path** (string) - Required - The path associated with the item.
  - **status** (string) - Required - The status of the item (e.g., 'Active', 'Paused', 'Done').
- **meta** (Object) - Required - An object mapping item names to their metadata.
- **suggesterOptions** (Object) - Optional - Options for the suggester, including `renderItem`.
  - **renderItem** (Function) - Optional - A function that receives `value` and `el` to render a suggestion item.

### Request Example
```json
{
  "items": [
    { "name": "Inbox", "path": "Projects/Inbox.md", "status": "Active" },
    { "name": "Roadmap", "path": "Projects/Roadmap.md", "status": "Paused" },
    { "name": "Backlog", "path": "Projects/Backlog.md", "status": "Done" }
  ],
  "meta": {
    "Inbox": { "name": "Inbox", "path": "Projects/Inbox.md", "status": "Active" },
    "Roadmap": { "name": "Roadmap", "path": "Projects/Roadmap.md", "status": "Paused" },
    "Backlog": { "name": "Backlog", "path": "Projects/Backlog.md", "status": "Done" }
  },
  "suggesterOptions": {
    "renderItem": "(value, el) => { ... custom rendering logic ... }"
  }
}
```

### Response
#### Success Response (200)
- **selectedItem** (string) - The selected item from the suggester.

#### Response Example
```json
{
  "selectedItem": "Inbox"
}
```
```

--------------------------------

### AI Module - getModels

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Retrieves a list of all available AI models configured in the QuickAdd settings.

```APIDOC
## AI Module - getModels

Access via `quickAddApi.ai`:

### `getModels(): string[]`

Returns available AI models.

**Example:**
```javascript
const models = quickAddApi.ai.getModels();
const selectedModel = await quickAddApi.suggester(models, models);
```
```

--------------------------------

### Handle List-Style Placeholders in QuickAdd Templates

Source: https://quickadd.obsidian.guide/docs/TemplatePropertyTypes

This example demonstrates how QuickAdd handles list-style placeholders within YAML front matter. It shows how to define 'sources' as a list and 'description' as a single string, respecting Obsidian's property types.

```yaml
---
sources:
  - "{{VALUE:sources}}"  
description: "{{VALUE:description}}"  
---

```

--------------------------------

### Send Prompt to AI Model with QuickAdd API (String Model)

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Sends a prompt to a specified AI model and returns the response. This example uses a string identifier for the model (e.g., 'gpt-4'). Optional settings allow customization of response variable names, model parameters, and display behavior.

```javascript
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}}
```

--------------------------------

### User Input Methods - wideInputPrompt

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

The `wideInputPrompt` method is similar to `inputPrompt` but designed for longer, multi-line text input.

```APIDOC
### `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:**
```javascript
const description = await quickAddApi.wideInputPrompt(
    "Project Description",
    "Enter a detailed description...",
    "This project aims to..."
);
```
```

--------------------------------

### Check Plugin Dependencies Macro

Source: https://quickadd.obsidian.guide/docs/Choices/MacroChoice

This JavaScript code demonstrates how to verify if a required Obsidian plugin is installed and enabled before proceeding with plugin-specific operations. It checks for the existence of the plugin using `app.plugins.plugins` and displays a notice if the plugin is not found. Dependencies include the Obsidian `app` object.

```javascript
module.exports = async (params) => {
    const { app } = params;
      
    const requiredPlugin = app.plugins.plugins["plugin-id"];
    if (!requiredPlugin) {
        new Notice("Required plugin not found!");
        return;
    }
      
    // Continue with plugin operations
};

```

--------------------------------

### Active File Editor Operations with Obsidian API

Source: https://quickadd.obsidian.guide/docs/UserScripts

Explains how to interact with the active file's editor in Obsidian, including getting selected text, cursor position, line content, and performing text replacements. Requires 'app' and 'obsidian' from params. Handles cases where no active file exists.

```javascript
async function start(params, settings) {
    const { app, obsidian } = params;
      
    // Get active file  
    const activeFile = app.workspace.getActiveFile();
    if (!activeFile) {
        new obsidian.Notice("No active file");
        return;
    }
      
    // Get active editor  
    const activeView = app.workspace.getActiveViewOfType(obsidian.MarkdownView);
    if (activeView) {
        const editor = activeView.editor;
          
        // Get selected text  
        const selection = editor.getSelection();
          
        // Get current line  
        const cursor = editor.getCursor();
        const line = editor.getLine(cursor.line);
          
        // Replace selection  
        editor.replaceSelection("New text");
          
        // Insert at cursor  
        editor.replaceRange(
            "Inserted text", 
            cursor
        );
          
        // Get entire document  
        const fullText = editor.getValue();
          
        // Replace entire document  
        editor.setValue("Completely new content");
    }
}
```

--------------------------------

### Example Google Books API JSON Response

Source: https://quickadd.obsidian.guide/docs/Examples/Macro_BookFinder

A sample JSON object representing a book's data obtained from the Google Books API. This structure includes details like title, authors, publisher, description, ISBN, and image links. Developers can extend JavaScript code to parse and extract more granular information from this response.

```json
{
  "kind": "books#volumes",
  "totalItems": 119,
  "items": [
    {
      "kind": "books#volume",
      "id": "6P_jN6zUuMcC",
      "etag": "FpDPG4koVaQ",
      "selfLink": "https://www.googleapis.com/books/v1/volumes/6P_jN6zUuMcC",
      "volumeInfo": {
        "title": "Flowers for Algernon",
        "authors": [
          "Daniel Keyes"
        ],
        "publisher": "Houghton Mifflin Harcourt",
        "publishedDate": "2004",
        "description": "Oscar-winning film Charly starring Cliff Robertson and Claire Bloom-a mentally challenged man receives an operation that turns him into a genius...and introduces him to heartache.",
        "industryIdentifiers": [
          {
            "type": "ISBN_13",
            "identifier": "9780156030083"
          },
          {
            "type": "ISBN_10",
            "identifier": "015603008X"
          }
        ],
        "readingModes": {
          "text": false,
          "image": true
        },
        "pageCount": 324,
        "printType": "BOOK",
        "categories": [
          "Fiction"
        ],
        "averageRating": 4,
        "ratingsCount": 179,
        "maturityRating": "NOT_MATURE",
        "allowAnonLogging": true,
        "contentVersion": "1.3.3.0.preview.1",
        "panelizationSummary": {
          "containsEpubBubbles": false,
          "containsImageBubbles": false
        },
        "imageLinks": {
          "smallThumbnail": "http://books.google.com/books/content?id=6P_jN6zUuMcC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
          "thumbnail": "http://books.google.com/books/content?id=6P_jN6zUuMcC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api"
        },
        "language": "en",
        "previewLink": "http://books.google.ca/books?id=6P_jN6zUuMcC&printsec=frontcover&dq=intitle:Flowers+for+Algernon&hl=&cd=1&source=gbs_api",
        "infoLink": "http://books.google.ca/books?id=6P_jN6zUuMcC&dq=intitle:Flowers+for+Algernon&hl=&source=gbs_api",
        "canonicalVolumeLink": "https://books.google.com/books/about/Flowers_for_Algernon.html?hl=&id=6P_jN6zUuMcC"
      },
      "saleInfo": {
        "country": "CA",
        "saleability": "NOT_FOR_SALE",
        "isEbook": false
      },
      "accessInfo": {
        "country": "CA",
        "viewability": "PARTIAL",
        "embeddable": true,
        "publicDomain": false,
        "textToSpeechPermission": "ALLOWED",
        "epub": {
          "isAvailable": false
        },
        "pdf": {
          "isAvailable": true,
          "acsTokenLink": "http://books.google.ca/books/download/Flowers_for_Algernon-sample-pdf.acsm?id=6P_jN6zUuMcC&format=pdf&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
        },
        "webReaderLink": "http://play.google.com/books/reader?id=6P_jN6zUuMcC&hl=&source=gbs_api",
        "accessViewStatus": "SAMPLE",
        "quoteSharingAllowed": false
      },
      "searchInfo": {
        "textSnippet": "WINNER OF THE HUGO AWARD AND THE NEBULA AWARD The classic novel that inspired the Academy Award-winning movie Charly Daniel Keyes, the author of eight books, was born in Brooklyn, New York, and received his B.A. and M.A. degrees from ..."
      }
    }
  ]
}
```

--------------------------------

### Execute Choice API

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Allows for the programmatic execution of another QuickAdd choice. This is useful for chaining workflows or triggering specific actions from within a script.

```APIDOC
## POST /api/choices/execute

### Description
Executes a specified QuickAdd choice by its name. This function can also accept an optional object of variables to pass to the executed choice, enabling dynamic data injection.

### Method
POST

### Endpoint
/api/choices/execute

### Parameters
#### Request Body
- **choiceName** (string) - Required - The name of the QuickAdd choice to execute.
- **variables** (Object) - Optional - A key-value map of variables to pass to the executed choice. The special key `value` maps to `{{VALUE}}`.

### Request Example
```json
{
  "choiceName": "Create Meeting Note",
  "variables": {
    "meetingTitle": "Project Review",
    "attendees": "John, Jane, Bob",
    "date": "2024-01-15",
    "value": "Main agenda content"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the choice execution.

#### Response Example
```json
{
  "status": "executed"
}
```
```

--------------------------------

### Field Suggestions Module

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Documentation for the `quickAddApi.fieldSuggestions` module, which allows retrieving and suggesting values for specific fields within your Obsidian vault.

```APIDOC
## Field Suggestions Module

Access the field suggestions functionality through `quickAddApi.fieldSuggestions`.

### `getFieldValues(fieldName: string, options?: object): Promise<string[]>`

Retrieves all unique values for a specified field across your entire Obsidian vault, with options for filtering.

#### Parameters

*   **`fieldName`** (string) - Required - The name of the metadata field (e.g., 'status', 'priority', 'type') for which to retrieve values.
*   **`options`** (object) - Optional - An object to filter the search scope:
    *   **`folder`** (string) - Limits the search to files within a specific folder path (e.g., "daily/notes").
    *   **`tags`** (string[]) - Limits the search to files that have one or more of the specified tags (e.g., `["work", "important"]`).
    *   **`includeInline`** (boolean) - If `true`, includes values from Dataview inline fields (default: `false`).

#### Returns

A `Promise` that resolves to a sorted array of unique string values found for the specified field.

#### Examples

**Basic Usage**: Get all unique values for the 'status' field across the vault.
```javascript
const statuses = await quickAddApi.fieldSuggestions.getFieldValues("status");
const selected = await quickAddApi.suggester(statuses, statuses);
```

**Folder Filter**: Get unique 'type' values only from files within the 'projects' folder.
```javascript
const projectTypes = await quickAddApi.fieldSuggestions.getFieldValues(
    "type",
    { folder: "projects" }
);
```

**Tag Filter**: Get unique 'priority' values from files tagged with 'work' or 'important'.
```javascript
const priorities = await quickAddApi.fieldSuggestions.getFieldValues(
    "priority",
    { tags: ["work", "important"] }
);
```

**Include Inline Fields**: Get all unique 'client' values, including those from inline fields, within the 'work/projects' folder.
```javascript
const clients = await quickAddApi.fieldSuggestions.getFieldValues(
    "client",
    {
        folder: "work/projects",
        includeInline: true
    }
);
```
```

--------------------------------

### Checkbox Prompt API

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Provides a function to display a checkbox prompt, allowing users to make multiple selections from a list of options. It also supports pre-selecting items.

```APIDOC
## POST /api/prompts/checkbox

### Description
Opens a prompt with checkboxes, enabling users to select multiple items from a provided list. Supports pre-selection of items.

### Method
POST

### Endpoint
/api/prompts/checkbox

### Parameters
#### Request Body
- **items** (Array<string>) - Required - The list of options to display in the prompt.
- **selectedItems** (Array<string>) - Optional - An array of items that should be pre-selected by default.

### Request Example
```json
{
  "items": ["Dark Mode", "Auto-save", "Spell Check", "Line Numbers"],
  "selectedItems": ["Auto-save", "Line Numbers"]
}
```

### Response
#### Success Response (200)
- **selectedItems** (Array<string>) - An array containing the items selected by the user.

#### Response Example
```json
{
  "selectedItems": ["Dark Mode", "Spell Check"]
}
```
```

--------------------------------

### User Input Methods - requestInputs

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

The `requestInputs` method allows collecting multiple user inputs through a single modal, supporting various field types and dynamic options.

```APIDOC
## User Input Methods

### `requestInputs(inputs: Array<{ id: string; label?: string; type: "text" | "textarea" | "dropdown" | "date" | "field-suggest" | "suggester"; placeholder?: string; defaultValue?: string; options?: string[]; dateFormat?: string; description?: string; suggesterConfig?: { allowCustomInput?: boolean; caseSensitive?: boolean; multiSelect?: boolean; } }>): Promise<Record<string, string>>`

Opens a one-page modal to collect multiple inputs in one go. Values already present in `variables` are used and not re-asked. Returned values are also stored into `variables`.

**Behavior:**
  * Uses existing values for any ids that already exist in `variables` (including empty strings).
  * Prompts only for missing (`undefined`/`null`) inputs.

**Field Types:**
  * `text`: Single-line text input
  * `textarea`: Multi-line text input
  * `dropdown`: Fixed dropdown menu (no search, must select from list)
  * `date`: Date input with natural language support
  * `field-suggest`: Vault field suggestions (uses `{{FIELD:...}}` syntax)
  * `suggester`: **NEW** - Searchable autocomplete with custom options (allows custom input) 
    * Supports multi-select mode via `suggesterConfig.multiSelect: true` for comma-separated selections

**Example:**
```javascript
const values = await quickAddApi.requestInputs([
  { id: "project", label: "Project", type: "text", defaultValue: "Inbox" },
  { id: "due", label: "Due", type: "date", dateFormat: "YYYY-MM-DD" },
  { id: "status", label: "Status", type: "dropdown", options: ["Todo","Doing","Done"] },
  {
    id: "tags",
    label: "Tags",
    type: "suggester",
    options: ["work", "personal", "urgent", "review"],
    placeholder: "Type to search tags...",
    suggesterConfig: { caseSensitive: false }
  }
]);
```

**Suggester with Dynamic Options (e.g., from Dataview):**

```javascript
// Get dynamic options from Dataview
const dv = app.plugins.plugins.dataview?.api;
const projectNames = dv?.pages()
  .where(p => p.type === "project")
  .map(p => p.file.name)
  .array() ?? ["Inbox"];

const values = await quickAddApi.requestInputs([
  {
    id: "project",
    label: "Select Project",
    type: "suggester",
    options: projectNames,
    placeholder: "Start typing project name..."
  }
]);
```

**Multi-Select Suggester:**

```javascript
// Select multiple tags, comma-separated
const values = await quickAddApi.requestInputs([
  {
    id: "tags",
    label: "Select Tags",
    type: "suggester",
    options: ["#work", "#personal", "#project", "#urgent", "#review"],
    suggesterConfig: {
      multiSelect: true,
      caseSensitive: false
    },
    placeholder: "Type or select multiple tags..."
  }
]);

// Result: values.tags = "#work, #project, #urgent"
// Split into array if needed:
const tagArray = values.tags.split(', ').filter(Boolean);
```
```

--------------------------------

### Custom Suggester Rendering with Custom Input

Source: https://quickadd.obsidian.guide/docs/QuickAddAPI

Allows custom rendering for suggester items and enables users to input new values. It highlights whether a selected value is new or existing, providing a hint to the user.

```javascript
// Highlights when value is new; stores result in variables.project  
module.exports = async (params) => {  
  const { quickAddApi } = params;  
  const values = ['Inbox', 'Roadmap', 'Backlog'];  
  
  const selected = await quickAddApi.suggester(  
    values,  
    values,  
    'Type a new project or pick…',  
    true, // allowCustomInput  
    {  
      renderItem: (value, el) => {  
        const isNew = !values.includes(value);  
        const row = el.createEl('div');  
  
        const title = row.createEl('div', { text: value });  
        title.setAttr('style', 'font-weight:600;');  
  
        const hint = isNew ? 'New project (press Enter to create)' : 'Existing project';  
        const sub = row.createEl('div', { text: hint });  
        sub.setAttr('style', 'font-size:12px;color:var(--text-muted);');  
      }  
    }  
  );  
  
  if (!selected) return;  
  params.variables.project = selected;  
  return selected;
};

```
Tokens:
Raw