# About
Source: https://docs.aisearchapi.io/api-reference/about

Welcome to AI Search API!

## What is AI Search API

Creating an AI agent that can access and utilize real-time web information presents significant technical challenges.
Traditional web scraping approaches lack scalability and demand specialized knowledge to implement effectively.
Existing search engine APIs fall short by returning potentially unrelated articles rather than providing direct
answers to queries, and they aren't designed with AI agent requirements in mind.

To address these limitations, we're proud to launch AI Search API - the first search engine purpose-built for AI agents.
AI Search API delivers an LLM-optimized search experience that prioritizes speed, efficiency, and reliable results.
While conventional search APIs like Serp or Google cater to general use cases, AI Search API specifically targets
AI developers and autonomous agents. We handle the entire information pipeline - from search and scraping to
filtering and extraction - delivering the most relevant online data through a single, streamlined API call.

You can now test the API directly through our [API Playground](https://app.aisearchapi.io/playground),

## Getting started

[Sign up](https://app.aisearchapi.io/join) for AI Search API to get your API key. You get 1,000 free API Credits. No credit card required.

To begin using the AI Search API with code, obtain your API key and visit our
[Authentication Guide](/api-reference/authentication) to explore the available endpoints.


# Authentication
Source: https://docs.aisearchapi.io/api-reference/authentication

This API documentation covers the REST endpoints for integrating with the AISearchAPI platform. These HTTP-based APIs work in any environment capable of making HTTP requests. For language-specific libraries and SDKs, check the libraries page.

## Base URL

```
https://api.aisearch.io
```

## Authentication

The AISearchAPI uses API keys to authenticate requests. You can create and manage your API keys through your organization settings. [Get your free API key](https://app.aisearchapi.io/dashboard)

```bash
curl https://api.aisearch.io/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY"
  -d {"prompt": "How much is Bitcoin worth today?"}
```

## Endpoints

* **[POST /v1/search](/api-reference/endpoint/search)** - Execute a search query
* **[GET /v1/balance](/api-reference/endpoint/balance)** - Get account balance


# Balance
Source: https://docs.aisearchapi.io/api-reference/endpoint/balance

GET /v1/balance
Get account balance



# Search
Source: https://docs.aisearchapi.io/api-reference/endpoint/search

POST /v1/search
Execute a search query.



# CrewAI
Source: https://docs.aisearchapi.io/api-reference/integrations/crewai



This is a **CrewAI integration** for the **AI Search API**.\
It connects your CrewAI agents with **context-aware search**, **multi-message prompts**, and **intelligent answers with citations**.

👉 Get started now:

* [Sign Up](https://app.aisearchapi.io/join)
* [Log In](https://app.aisearchapi.io/login)
* [Dashboard](https://app.aisearchapi.io/dashboard)

***

# Features

* 🔍 **Prompt + Context Search** – Send a query with structured context
* 💬 **Multi-Message Context** – Handle several user messages in one query
* 📚 **Source Citations** – Responses include references when available
* ⚡ **CrewAI Integration** – Works with Agent, Task, Crew right away
* 🖥️ **Local LLM Support** – Use Ollama for reasoning + Search API for live info
* 🛡️ **Error Handling** – Clear exceptions for invalid models or roles

***

# Installation

```bash
pip install crewai-aisearchapi
```

***

# Quick Start (with Ollama + CrewAI)

```python
from crewai import Agent, Task, Crew, Process, LLM
from crewai_aisearchapi import AISearchTool

llm = LLM(
    model="ollama/llama3.2:3b",
    base_url="http://localhost:11434",
    temperature=0.2,
)

tool = AISearchTool(api_key="your-api-key")

agent = Agent(
    role="Researcher",
    goal="Answer questions with context and sources.",
    backstory="Careful and concise.",
    tools=[tool],
    llm=llm,
    verbose=True,
)

task = Task(
    description="Answer: '{question}'. Keep it short.",
    expected_output="2–4 sentences.",
    agent=agent,
    markdown=True,
)

crew = Crew(agents=[agent], tasks=[task], process=Process.sequential, verbose=True)

if __name__ == "__main__":
    print(crew.kickoff(inputs={"question": "What is RLHF in AI?"}))
```

***

# Contextual Prompts

Add multiple context messages for better answers:

```python
result = tool.run({
    "prompt": "Explain how RLHF improves AI safety.",
    "context": [
        {"role": "user", "content": "Keep it simple, I'm new to ML."},
        {"role": "user", "content": "Add one practical example."}
    ],
    "response_type": "markdown"
})
```

***

# Configuration Options

```python
from crewai_aisearchapi import AISearchTool, AISearchToolConfig

config = AISearchToolConfig(
    default_response_type="markdown",
    include_sources=True,
    timeout=30,
    verbose=True
)

tool = AISearchTool(api_key="your-api-key", config=config)
```

***

# Handling Responses

The tool returns:

* **Answer** (AI response)
* **Sources** (when available)
* **Response time**

Example:

```text
Reinforcement Learning with Human Feedback (RLHF) helps align AI models with human intent...

**Sources:**
- [1] https://example.com/rlhf-overview
- [2] https://research.example.org/rlhf

*Response time: 120ms*
```

***

# Environment Variables

```bash
export AISEARCH_API_KEY="your-api-key"
```

In Python:

```python
import os
from crewai_aisearchapi import AISearchTool

tool = AISearchTool(api_key=os.getenv("AISEARCH_API_KEY"))
```

***

# Troubleshooting

| Problem                | Fix                                              |
| ---------------------- | ------------------------------------------------ |
| **model not found**    | Run `ollama pull llama3.2:3b`                    |
| **context role error** | Ensure all context messages use `"role": "user"` |
| **API key error**      | Check `AISEARCH_API_KEY` is set correctly        |

***

# Resources

* [AI Search API Homepage](https://aisearchapi.io)
* [Docs](https://docs.aisearchapi.io)
* [Dashboard](https://app.aisearchapi.io/dashboard)
* [GitHub Issues](https://github.com/aisearchapi/aisearchapi-py/issues)

***

# License

[MIT License](https://github.com/aisearchapi/aisearchapi-crew-ai/blob/main/LICENSE)

***


# Node.js SDK
Source: https://docs.aisearchapi.io/api-reference/integrations/javascript



This SDK helps you use the **AI Search API** in your Node.js or TypeScript projects.\
It gives you **semantic search** with context, flexible response formats, and strong TypeScript support.

👉 To start, create a free account:

* [Sign Up](https://app.aisearchapi.io/join)
* [Log In](https://app.aisearchapi.io/login)
* [Dashboard](https://app.aisearchapi.io/dashboard) (get and manage your API keys)

## Features

* 🔍 **Semantic AI Search** – Ask natural language questions
* 💬 **Context Awareness** – Add chat-like history
* 📝 **Flexible Responses** – Choose Markdown or plain text
* ⚡ **TypeScript First** – IntelliSense & type safety
* 📊 **Usage Tracking** – Check your credits anytime

***

# Installation

You can install the SDK with **npm** or **yarn**:

```bash
npm install aisearchapi-client
# or
yarn add aisearchapi-client
```

Or install from source:

```bash
git clone https://github.com/aisearchapi/aisearchapi-js.git
cd aisearchapi-js
npm install
```

***

# Quick Start

Import and create a client with your API key:

```ts
import { AISearchAPIClient } from 'aisearchapi-client';

const client = new AISearchAPIClient({
  apiKey: 'your-api-key-here' // get it from the Dashboard
});

const result = await client.search({
  prompt: 'What is machine learning and how does it work?',
  response_type: 'markdown'
});

console.log(result.answer);
console.log('Sources:', result.sources);
```

***

# API Reference

## Client Configuration

```ts
const client = new AISearchAPIClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.aisearchapi.io',
  timeout: 30000 // ms
});
```

## Search

```ts
const result = await client.search({
  prompt: 'Your query',
  context: [{ role: 'user', content: 'Previous message' }],
  response_type: 'markdown'
});
```

## Balance

```ts
const balance = await client.balance();
console.log('Credits left:', balance.available_credits);
```

***

# Usage Examples

### Basic Search

```ts
const result = await client.search({ prompt: 'Explain quantum computing simply' });
console.log(result.answer);
```

### Contextual Search

```ts
const result = await client.search({
  prompt: 'What are the benefits?',
  context: [
    { role: 'user', content: 'I am researching renewable energy' },
    { role: 'user', content: 'Specifically solar and wind' }
  ]
});
```

### Check Balance

```ts
const balance = await client.balance();
if (balance.available_credits < 10) {
  console.warn('Low balance!');
}
```

### Error Handling

```ts
import { AISearchAPIError } from 'aisearchapi-client';

try {
  const result = await client.search({ prompt: 'Hello' });
} catch (error) {
  if (error instanceof AISearchAPIError) {
    console.error(`API Error [${error.statusCode}]:`, error.message);
  }
}
```

***

# TypeScript Support

This client is written in TypeScript. You can use strong typing:

```ts
import type { SearchRequest, SearchResponse } from 'aisearchapi-client';

const params: SearchRequest = {
  prompt: 'What is TypeScript?',
  response_type: 'markdown'
};

const response: SearchResponse = await client.search(params);
```

***

# Response Formats

You can choose how answers are returned:

* **Markdown (default):** rich formatting, lists, code blocks
* **Text:** simple string

```ts
await client.search({ prompt: 'Explain REST APIs', response_type: 'markdown' });
await client.search({ prompt: 'Explain Node.js', response_type: 'text' });
```

***

# Error Codes

| Code | Meaning           | Fix                             |
| ---- | ----------------- | ------------------------------- |
| 401  | Unauthorized      | Invalid API key → get a new one |
| 429  | Too Many Requests | Rate limit hit                  |
| 433  | Quota Exceeded    | Credits finished                |
| 500  | Server Error      | Try again later                 |
| 503  | Service Down      | Maintenance                     |

***

# Environment Variables

You can store your API key in `.env`:

```env
AI_SEARCH_API_KEY=your-key-here
```

Then use it in your code:

```ts
const client = new AISearchAPIClient({
  apiKey: process.env.AI_SEARCH_API_KEY!
});
```

***

# Browser Support

This SDK is made for **Node.js**.\
For browser use:

* Configure CORS
* Keep your API keys secure

***

# Resources

* [AI Search API Homepage](https://aisearchapi.io)
* [Join](https://app.aisearchapi.io/join) | [Login](https://app.aisearchapi.io/login) | [Dashboard](https://app.aisearchapi.io/dashboard)
* [npm Package](https://www.npmjs.com/package/aisearchapi-client)
* [Issues](https://github.com/aisearchapi/aisearchapi-js/issues)
* [Blog](https://aisearchapi.io/blog)

***


# LangChain
Source: https://docs.aisearchapi.io/api-reference/integrations/langchain



This package integrates the **AI Search API** with **LangChain**.\
You can use semantic search, conversational models, and AI agents in your LangChain projects with just one package.

👉 To start, create an account and get your API key:

* [Sign Up](https://app.aisearchapi.io/join)
* [Log In](https://app.aisearchapi.io/login)
* [Dashboard](https://app.aisearchapi.io/dashboard)

***

# Features

* 🔑 **One Package Setup** – `pip install langchain-aisearchapi` and you’re ready
* 🤖 **LLM Interface** – Use AI Search API as a LangChain LLM
* 💬 **Chat Model** – Build conversational agents with memory
* 🛠️ **Tools for Agents** – Add AI Search directly into LangChain workflows
* 📚 **Prebuilt Chains** – Research, Q\&A, fact-checking out of the box

***

# Installation

Install from PyPI:

```bash
pip install langchain-aisearchapi
```

That’s it — no extra setup needed.

***

# Quick Start

## 1. Basic LLM Usage

```python
from langchain_aisearchapi import AISearchLLM

llm = AISearchLLM(api_key="your-key")
response = llm("Explain semantic search in simple terms")
print(response)
```

## 2. Conversational Chat

```python
from langchain_aisearchapi import AISearchChat
from langchain.schema import HumanMessage

chat = AISearchChat(api_key="your-key")

messages = [
    HumanMessage(content="What is LangChain?"),
    HumanMessage(content="Why do developers use it?")
]

response = chat(messages)
print(response.content)
```

## 3. AI Search as a Tool in Agents

```python
from langchain_aisearchapi import AISearchTool, AISearchLLM
from langchain.agents import initialize_agent, AgentType

search_tool = AISearchTool(api_key="your-key")
llm = AISearchLLM(api_key="your-key")

agent = initialize_agent(
    tools=[search_tool],
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

result = agent.run("Find the latest SpaceX launch details")
print(result)
```

## 4. Research Assistant

```python
from langchain_aisearchapi import create_research_chain

research = create_research_chain(api_key="your-key")
result = research.run("Breakthroughs in AI search technology 2024")
print(result)
```

***

# Components

| Component                 | Description               | Use Case                      |
| ------------------------- | ------------------------- | ----------------------------- |
| `AISearchLLM`             | AI Search API as an LLM   | Completions, text generation  |
| `AISearchChat`            | Chat model with context   | Conversational AI, assistants |
| `AISearchTool`            | Search as LangChain tool  | Agents, workflows             |
| `create_research_chain()` | Ready-made research chain | Research and reporting        |

***

# Troubleshooting

* ❌ **No API key?** → [Sign up](https://app.aisearchapi.io/join) or log in.
* 🔑 **Key issues?** → Check your [dashboard](https://app.aisearchapi.io/dashboard).
* ⏳ **Rate limited?** → Use retry logic (e.g. with `tenacity`).

***

# Resources

* [AI Search API Homepage](https://aisearchapi.io)
* [Sign Up](https://app.aisearchapi.io/join) / [Log In](https://app.aisearchapi.io/login) / [Dashboard](https://app.aisearchapi.io/dashboard)
* [PyPI Package](https://pypi.org/project/langchain-aisearchapi)
* [Blog](https://aisearchapi.io/blog)

***

# Start Now

Install the package, get your API key, and build powerful LangChain apps with the AI Search API:

```bash
pip install langchain-aisearchapi
```

👉 [Join now](https://app.aisearchapi.io/join) to claim your free API key and start building!

***


# MCP
Source: https://docs.aisearchapi.io/api-reference/integrations/mcp



This is a **Model Context Protocol (MCP)** server that integrates the **AI Search API** into MCP-compatible apps.\
It brings **semantic search**, **context awareness**, and **source citations** directly into your workflows.

👉 Get started now:

* [Sign Up](https://app.aisearchapi.io/join)
* [Log In](https://app.aisearchapi.io/login)
* [Dashboard](https://app.aisearchapi.io/dashboard) (manage your API key)

***

# Features

* 🔍 **Intelligent Semantic Search** – Natural language queries with embeddings
* 💬 **Context Management** – Keep or clear conversation history
* 📝 **Flexible Responses** – Markdown or plain text output
* 📚 **Source Citations** – Reliable references included
* 📊 **Balance Monitoring** – Track credits in real time
* ⚡ **TypeScript Support** – Strong typing & IDE hints

***

# Installation

## From npm (recommended)

```bash
npm install -g aisearchapi-mcp
```

## From source

```bash
git clone https://github.com/aisearchapi/aisearchapi-mcp.git
cd aisearchapi-mcp
npm install
npm run build
```

***

# Configuration

## 1. Get API Key

Create an account and copy your key:

* [Join](https://app.aisearchapi.io/join) | [Login](https://app.aisearchapi.io/login) | [Dashboard](https://app.aisearchapi.io/dashboard)

## 2. Environment Variables

Set up `.env` file:

```env
AISEARCHAPI_KEY=your-api-key-here
AISEARCHAPI_BASE_URL=https://api.aisearchapi.io
AISEARCHAPI_TIMEOUT=30000
AISEARCHAPI_VERBOSE=false
```

***

# Configure Claude for Desktop

First, install **Claude Code**:

```bash
npm install -g @anthropic-ai/claude-code
```

Go through the authorization process to access Claude Code.\
Then set up your local MCP:

```bash
claude mcp add aisearchapi "npx -y aisearchapi-mcp" --env API_KEY=<YOUR-API-KEY>
```

Check if it’s added correctly:

```bash
claude mcp list
```

You should see:

```
Checking MCP server health...
aisearchapi: npx -y aisearchapi-mcp  - ✓ Connected
```

Now you’re ready to go!

***

# Command Line Usage

List available tools:

```bash
node dist/index.js --list-tools
```

Check balance:

```bash
node dist/index.js --check-balance
```

Run the server:

```bash
node dist/index.js
```

***

# Error Codes

| Code | Meaning           | Fix                          |
| ---- | ----------------- | ---------------------------- |
| 401  | Unauthorized      | Invalid key → Get a new key  |
| 429  | Too Many Requests | Slow down or add retry logic |
| 433  | Quota Exceeded    | Buy credits / upgrade        |
| 500  | Server Error      | Try again later              |
| 503  | Service Down      | Temporary downtime           |

***

# Development

```bash
git clone https://github.com/aisearchapi/aisearchapi-mcp.git
cd aisearchapi-mcp
npm install
npm run build
npm run dev
```

***

# Best Practices

* Clear context when switching topics
* Use markdown output for richer UI
* Monitor credits regularly
* Secure your API key with environment variables

***

# Resources

* [AI Search API Homepage](https://aisearchapi.io)
* [Join](https://app.aisearchapi.io/join) | [Login](https://app.aisearchapi.io/login) | [Dashboard](https://app.aisearchapi.io/dashboard)
* [npm Package](https://www.npmjs.com/package/aisearchapi-mcp)
* [Issues](https://github.com/aisearchapi/aisearchapi-mcp/issues)
* [Blog](https://aisearchapi.io/blog)

***

# Start Now

Install the package, configure Claude Desktop, and start searching with the AI Search API MCP Server:

```bash
npm install -g aisearchapi-mcp
```

***


# n8n Node
Source: https://docs.aisearchapi.io/api-reference/integrations/n8n



This is a **custom n8n node** for integrating the **AI Search API** into your automation workflows.\
It brings **semantic search**, **context awareness**, and **balance monitoring** directly into your n8n pipelines.

👉 Get started now:

* [Sign Up](https://app.aisearchapi.io/join)
* [Log In](https://app.aisearchapi.io/login)
* [Dashboard](https://app.aisearchapi.io/dashboard)

***

# Features

* 🔍 **Intelligent Semantic Search** – Natural language queries with embeddings
* 💬 **Context Management** – Add previous messages for richer answers
* 📝 **Flexible Responses** – Markdown or plain text output
* 📊 **Balance Monitoring** – Track credits and usage in real time
* ⚡ **TypeScript Support** – Strong typings and IDE hints
* 🧩 **n8n Ready** – Works as a drag-and-drop node inside your n8n editor

***

# Installation

## From npm (recommended)

```bash
npm install n8n-nodes-aisearchapi
```

## From source

```bash
git clone https://github.com/aisearchapi/aisearchapi-n8n.git
cd aisearchapi-n8n
npm install
npm run build
```

***

# Run n8n with Your Extension

## Windows PowerShell (edit the path)

```powershell
docker run -it --rm -p 5678:5678 `
  -e N8N_CUSTOM_EXTENSIONS=/extensions `
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true `
  -e DB_SQLITE_POOL_SIZE=5 `
  -e N8N_RUNNERS_ENABLED=true `
  -v "C:\n8n-extensions\aisearchapi-n8n:/extensions" `
  -v n8n_data:/home/node/.n8n `
  n8nio/n8n:latest
```

## macOS / Linux / WSL (edit the path)

```bash
docker run -it --rm -p 5678:5678   -e N8N_CUSTOM_EXTENSIONS=/extensions   -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true   -e DB_SQLITE_POOL_SIZE=5   -e N8N_RUNNERS_ENABLED=true   -v "$HOME/n8n-extensions/aisearchapi-n8n:/extensions"   -v n8n_data:/home/node/.n8n   n8nio/n8n:latest
```

Then open: [http://localhost:5678](http://localhost:5678)\
You should see: `Loaded extensions from /extensions`

***

# Configuration in n8n

1. Go to **Credentials → New → AI Search API**
2. Paste your **API Key** (without the `Bearer` prefix)
3. Save credentials

***

# Usage

## Search

* **Resource:** Search
* **Operation:** Search
* **Parameters:**
  * `query` → your question (required)
  * `responseType` → `markdown | text`
  * `context` → optional array of messages
  * `timeout` → ms (default 30000)

## Balance

* **Resource:** Account
* **Operation:** Get Balance

***

# Error Codes

| Code | Meaning           | Fix                         |
| ---- | ----------------- | --------------------------- |
| 401  | Unauthorized      | Invalid key → Get a new key |
| 429  | Too Many Requests | Slow down / add retry logic |
| 433  | Quota Exceeded    | Buy credits / upgrade       |
| 500  | Server Error      | Try again later             |
| 503  | Service Down      | Temporary downtime          |

***

# Development

```bash
git clone https://github.com/aisearchapi/aisearchapi-n8n.git
cd aisearchapi-n8n
npm install
npm run build
```

You should see compiled files:

* `dist/credentials/AiSearchApi.credentials.js`
* `dist/nodes/AiSearchApi/AiSearchApi.node.js`

**package.json important parts:**

```json
{
  "name": "n8n-nodes-aisearchapi",
  "version": "0.1.0",
  "main": "dist/index.js",
  "files": ["dist", "README.md", "LICENSE"],
  "keywords": ["n8n", "n8n-community-node-package", "AI Search API", "semantic search", "automation"],
  "n8n": {
    "nodes": ["dist/nodes/AiSearchApi/AiSearchApi.node.js"],
    "credentials": ["dist/credentials/AiSearchApi.credentials.js"]
  }
}
```

***

# TypeScript Config

CommonJS build to avoid ESM issues:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": ".",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true
  },
  "include": ["credentials/**/*", "nodes/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
```

***

# Logos / Icons

Put your SVGs in:

* `nodes/AiSearchApi/aisearchapi.svg`
* `credentials/aisearchapi.svg`

Build script copies them next to compiled files in `dist/...`

***

# Best Practices

* Keep your API key secret (use n8n Credentials)
* Use **Markdown** output for rich UI
* Reset context when changing topics
* Watch your credits with the **balance endpoint**

***

# Troubleshooting

* **Node not visible in n8n** → Check build files exist, restart Docker, verify mounted path
* **Cannot find package 'n8n-workflow'** → Install it: `npm i n8n-workflow@1.108.2`
* **Build issues on Windows** → Use `shx` for copy operations instead of `cp`

***

# Resources

* [AI Search API Homepage](https://aisearchapi.io)
* [Sign Up](https://app.aisearchapi.io/join) | [Log In](https://app.aisearchapi.io/login) | [Dashboard](https://app.aisearchapi.io/dashboard)
* [GitHub Issues](https://github.com/aisearchapi/aisearchapi-n8n/issues)
* [npm Package](https://www.npmjs.com/package/n8n-nodes-aisearchapi)
* [Blog](https://aisearchapi.io/blog)

***

# Start Now

Install and connect your API key in n8n, then start building AI-powered workflows:

```bash
npm install n8n-nodes-aisearchapi
```

***


# Python SDK
Source: https://docs.aisearchapi.io/api-reference/integrations/python



This SDK helps you use the **AI Search API** in your Python projects.\
It gives you **semantic search**, context support, and flexible outputs with a simple Pythonic interface.

👉 To start, get your free API key from the [AI Search API dashboard](https://app.aisearchapi.io/dashboard).

## Features

* 🔍 **AI-Powered Semantic Search** – Use advanced embeddings for natural language queries
* 🎯 **Context Awareness** – Add chat-like history for smarter results
* ⚡ **Simple API Client** – Clean Python interface with error handling
* 🛡️ **Type Safety** – Full type hints for modern Python
* 🔄 **Flexible Output** – Choose plain text or markdown responses
* 💰 **Usage Tracking** – Monitor your credits anytime

***

# Installation

Install from PyPI:

```bash
pip install aisearchapi-client
```

Or install from source:

```bash
git clone https://github.com/aisearchapi/aisearchapi-python.git
cd aisearchapi-python
pip install -e .
```

***

# Quick Start

## Get Your API Key

1. [Sign up](https://app.aisearchapi.io/join)
2. [Log in](https://app.aisearchapi.io/login)
3. Copy your API key from the dashboard.

## Basic Usage Example

```python
from aisearchapi_client import AISearchAPIClient

client = AISearchAPIClient(api_key="your-api-key-here")

result = client.search(
    prompt="What is machine learning and how does it work?",
    response_type="markdown"
)

print("Answer:", result.answer)
print("Sources:", result.sources)
print(f"Total time: {result.total_time}ms")

balance = client.balance()
print(f"Available credits: {balance.available_credits}")
client.close()
```

***

# Advanced Usage

## Contextual Search

```python
from aisearchapi_client import AISearchAPIClient, ChatMessage

with AISearchAPIClient(api_key="your-api-key-here") as client:
    result = client.search(
        prompt="What are the main advantages and disadvantages?",
        context=[
            ChatMessage(role="user", content="I am researching solar energy for my home"),
            ChatMessage(role="user", content="I live in a sunny climate with high electricity costs")
        ],
        response_type="text"
    )
    print("Contextual Answer:", result.answer)
```

## Custom Configuration

```python
client = AISearchAPIClient(
    api_key="your-api-key-here",
    base_url="https://api.aisearchapi.io",
    timeout=60
)
```

***

# API Reference

## AISearchAPIClient

### Constructor

```python
AISearchAPIClient(
    api_key: str,
    base_url: str = "https://api.aisearchapi.io",
    timeout: int = 30
)
```

* `api_key`: Get yours from the dashboard
* `base_url`: Optional custom endpoint
* `timeout`: Timeout in seconds

### Methods

* `search(prompt, context=None, response_type=None)` → Run an AI-powered search
* `balance()` → Check available credits

***

# Error Handling

```python
from aisearchapi_client import AISearchAPIClient, AISearchAPIError

try:
    with AISearchAPIClient(api_key="your-api-key") as client:
        result = client.search(prompt="Your query")
        print(result.answer)
except AISearchAPIError as e:
    print(f"API Error [{e.status_code}]: {e.description}")
```

***

# Environment Variables

You can set your API key globally:

```bash
export AI_SEARCH_API_KEY="your-api-key-here"
```

Then use it in Python:

```python
import os
from aisearchapi_client import AISearchAPIClient

api_key = os.getenv("AI_SEARCH_API_KEY")
client = AISearchAPIClient(api_key=api_key)
```

***

# Examples

* Basic search and balance check
* Contextual search with history
* Async usage
* Error handling

Find more examples in the `examples/` folder.

***

# Requirements

* Python 3.8+
* `requests >= 2.25.0`
* `typing-extensions >= 4.0.0` (if Python \< 3.10)

***

# Development

```bash
git clone https://github.com/aisearchapi/aisearchapi-python.git
cd aisearchapi-python
python -m venv venv
source venv/bin/activate
pip install -e ".[dev,test]"
pytest
```

***

# License

This project is licensed under the **MIT License** – see the LICENSE file.

***

# Resources

* [Get API Key – Dashboard](https://app.aisearchapi.io/dashboard)
* [Homepage](https://aisearchapi.io)
* [Issues](https://github.com/aisearchapi/aisearchapi-python/issues)
* [Blog](https://aisearchapi.io/blog)

***