OpenAI Web Search Plugin for TypingMind

Exclusively designed for TypingMind — Bring real-time web search capabilities to your TypingMind AI assistant using OpenAI's Responses API with built-in web_search tool.

This plugin enables web search functionality for up-to-date information, current events, and real-time data beyond the AI's knowledge cutoff. Powered by OpenAI's gpt-5 reasoning model with automatic source citations.

---

🚀 Quick Start

1. Import Plugin: Visit TypingMind Plugins Documentation for import instructions (supports URL, GitHub URL, or JSON file import)
2. Add API Key: Get your OpenAI API key from platform.openai.com and paste it in plugin settings
3. Start Searching: Ask your AI assistant to "search the web for [query]" or ask questions requiring current information

---

Features

• Real-time Web Search: Leverages OpenAI's web_search tool via Responses API for current information
• Automatic Source Citations: OpenAI's API returns structured url_citation annotations with titles and URLs embedded in responses
• Configurable Reasoning Effort: Control search depth with low (fast), medium (balanced), or high (thorough) reasoning levels
• Geographic Localization: Optional user_location parameters (country, city, region, timezone) for location-specific results
• Model Flexibility: Supports gpt-5 (default) and o4-mini for different speed/thoroughness tradeoffs
• TypingMind Integration: Native function calling interface with respond_to_ai output type for seamless conversation flow

Usage

The plugin operates via function calling: when the AI detects queries requiring real-time data, it automatically invokes the openai_web_search function with the user's query. You can also explicitly trigger searches.

Example Queries

Current Events & News

"What are the top news stories today?"
"Search the web for recent developments in AI regulation"

Real-time Data Lookups

"What's the current weather in London?"
"Find the latest stock price for Tesla"

Location-aware Searches (requires location configuration)

"What are the best restaurants near Times Square?"
"Local news in [your configured city]"

Research with Citations

"Find recent studies on climate change effects"
"What are experts saying about cryptocurrency trends in 2025?"

Configuration

Required Parameters

Parameter	Type	Description
API Key	password	OpenAI API key from platform.openai.com/account/api-keys

Model Parameters

Parameter	Default	Options	Description
model	gpt-5	gpt-5, o4-mini	Model for web search processing. gpt-5 recommended for reasoning quality.
reasoning_effort	medium	low, medium, high	Search thoroughness: low = fast, high = comprehensive (slower)

Geographic Localization (Optional)

All location parameters are optional. Configure for location-specific results.

Parameter	Format	Example	Description
country	ISO 3166-1 alpha-2	US, GB, DE	Two-letter country code
city	String	New York, London	City name for local results
region	String	California, England	State/region for additional context
timezone	IANA	America/New_York	Timezone for time-sensitive queries

Implementation Note: Location parameters are passed to OpenAI's user_location field as type: "approximate" in the web_search tool configuration.

Technical Architecture

Request Flow

1. Function Invocation: TypingMind AI invokes openai_web_search function with user query
2. API Request: Plugin sends POST request to https://api.openai.com/v1/responses with:

   {
     "model": "gpt-5",
     "tools": [{"type": "web_search", "user_location": {...}}],
     "reasoning": {"effort": "medium"},
     "input": "<user query>"
   }

3. Web Search Execution: OpenAI's web_search tool queries the web with specified parameters
4. Response Processing: Model analyzes results and generates response with reasoning
5. Result Transform: JMESPath expression output[?type=='message']|[0].content[] extracts message content
6. Citation Delivery: Structured url_citation annotations are embedded in response content

Response Structure

OpenAI returns responses with:

• Content Array: Text blocks containing the answer
• Annotations: Array of url_citation objects with:
  • type: "url_citation"
  • title: Source document title
  • url: Clickable source URL
  • index: Citation reference number (may be null)

Example API Response Fragment:

{
  "output": [{
    "type": "message",
    "content": [{
      "text": "According to recent reports...",
      "annotations": [{
        "type": "url_citation",
        "title": "AI Industry Report 2025",
        "url": "https://example.com/report"
      }]
    }]
  }]
}

Best Practices

• Query Specificity: Precise queries yield better results

  • ✅ "Key announcements at Apple's October 2025 event"
  • ❌ "Apple news"

• Location Configuration: Set location parameters for local searches ("best pizza near me" requires city/region)

• Reasoning Effort Tuning:

  • low: Simple fact lookups, quick queries
  • medium: Default for most use cases
  • high: Complex research, multi-source analysis (increased latency)

• Explicit Search Triggers: Prepend queries with "Search the web for..." or "Find current information about..." if automatic invocation fails

Limitations & Constraints

• Geographic Availability: OpenAI web_search tool availability varies by region
• Context Window: 128,000 token limit for Responses API
• Model Support: Reasoning effort parameters require reasoning-capable models (gpt-5, o4-mini)
• Rate Limits: Subject to OpenAI API rate limits (requests per minute/day based on tier)
• Search Scope: Results depend on OpenAI's web indexing and real-time availability

Pricing

Web search invokes OpenAI's built-in web_search tool, incurring additional costs per search action beyond base model tokens. Consult OpenAI Pricing under "Built-in Tools" for current rates.

Troubleshooting

Issue	Diagnosis	Solution
Function not invoked	AI doesn't trigger search	• Explicitly include "search the web" in query • Verify API key validity • Confirm model is gpt-5 or o4-mini
Location data ignored	Geographic parameters not applied	• Use ISO 3166-1 alpha-2 codes for country • Verify IANA timezone format • Check all location fields are strings (not empty objects)
High latency	Searches taking too long	• Reduce reasoning_effort to low or medium • Note: high effort increases processing time significantly
API errors	401/403/429 responses	• Verify API key has valid billing • Check rate limits at platform.openai.com • Confirm web_search is enabled for your region

Plugin Implementation Details

TypingMind Plugin Specification

• Implementation Type: http (HTTP-based API plugin)
• Output Type: respond_to_ai (results feed back into AI conversation)
• Result Transform Engine: jmes (JMESPath for response parsing)
• Transform Expression: output[?type=='message']|[0].content[]

Citation Implementation

✅ Source citations are automatically included via OpenAI's Responses API:

• OpenAI's API returns url_citation annotation objects embedded in response content
• Each citation includes:
  • type: "url_citation"
  • title: Source document title
  • url: Full URL to original source
  • index: Reference number for inline citation
• Citations appear as structured annotations in the content array
• TypingMind renders these annotations as clickable links in the AI response

Note: Citation format and rendering depend on TypingMind's handling of annotation objects returned by the plugin.

---

Import Instructions

To add this plugin to your TypingMind instance:

1. Via URL: Copy plugin URL and paste into TypingMind's plugin import dialog
2. Via GitHub: Use repository URL (append ?token=<PAT> for private repos with read-only Contents permission)
3. Via JSON: Download plugin.json and use "Import plugin from JSON" option in TypingMind

Full instructions: docs.typingmind.com/plugins/share-import-plugins

---

Resources & Support

• Plugin Import Guide: docs.typingmind.com/plugins/share-import-plugins
• TypingMind Documentation: docs.typingmind.com
• OpenAI Responses API: platform.openai.com/docs/api-reference/responses
• API Key & Usage: platform.openai.com/account/api-keys

License

MIT License - See LICENSE file for details