Mino

https://docs.mino.ai
Admin
Mino is an AI-powered web automation platform that enables enterprises, builders, and developers to...
Tokens:52,724
Snippets:346
Trust Score:5.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Environment Setup

Source: https://docs.mino.ai/install-with-ai

Instructions on how to set up your environment variables, including obtaining and configuring your API key.

```APIDOC
## Environment Setup

### Description
Set up your environment variables by obtaining your API key from [https://agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys) and adding it to your `.env` file.

### Code
```bash
# Get your API key at https://agent.tinyfish.ai/api-keys
# Add to .env file:
TINYFISH_API_KEY=sk-tinyfish-*****
```
```

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

### Execute Python Workflow

Source: https://docs.mino.ai/quick-start

This command runs a Python script named 'first_automation.py'. Ensure you have Python and the necessary libraries (like requests and python-dotenv) installed.

```bash
python first_automation.py
```

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

### Environment Variable Setup for API Key

Source: https://docs.mino.ai/quick-start

This snippet shows how to store your TinyFish API key securely in a .env file. It is crucial to keep API keys confidential and avoid committing them to version control.

```bash
TINYFISH_API_KEY=sk-mino-*****
```

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

### Run First Workflow with cURL

Source: https://docs.mino.ai/quick-start

This cURL command demonstrates how to initiate a web automation task by sending a POST request to the TinyFish API. It includes the target URL and a natural language goal for the automation.

```bash
curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
            "url": "https://scrapeme.live/shop",
            "goal": "Extract the first 2 product names and prices"
          }'
```

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

### Setup Environment Variables for TinyFish API Key

Source: https://docs.mino.ai/install-with-ai

This snippet shows how to set up your environment variables, specifically the TINYFISH_API_KEY, which is required for authenticating with the TinyFish API. It's recommended to store sensitive keys in a .env file.

```bash
# Get your API key at https://agent.tinyfish.ai/api-keys
# Add to .env file:
TINYFISH_API_KEY=sk-tinyfish-*****
```

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

### Run SSE Automation

Source: https://docs.mino.ai/quick-start

This endpoint allows you to run a web automation task using Server-Sent Events (SSE). You provide a URL and a natural language goal, and the API streams the results back to you.

```APIDOC
## POST /v1/automation/run-sse

### Description
Initiates a web automation task and streams results via Server-Sent Events (SSE).

### Method
POST

### Endpoint
https://agent.tinyfish.ai/v1/automation/run-sse

### Parameters
#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - A natural language description of the task to perform.

### Request Example
```json
{
  "url": "https://scrapeme.live/shop",
  "goal": "Extract the first 2 product names and prices"
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of SSE event (e.g., STARTED, STREAMING_URL, PROGRESS, COMPLETE).
- **runId** (string) - A unique identifier for the automation run.
- **streamingUrl** (string) - The URL for streaming detailed results (if applicable).
- **purpose** (string) - Description of the current progress step (if type is PROGRESS).
- **status** (string) - The final status of the automation run (if type is COMPLETE).
- **resultJson** (object) - The final result of the automation in JSON format (if type is COMPLETE).

#### Response Example
```json
{
  "type": "COMPLETE",
  "runId": "abc123",
  "status": "COMPLETED",
  "resultJson": {
    "products": [
      { "name": "Bulbasaur", "price": "$63.00" },
      { "name": "Ivysaur", "price": "$87.00" }
    ]
  }
}
```
```

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

### Execute JavaScript/TypeScript Workflow

Source: https://docs.mino.ai/quick-start

This command executes a JavaScript or TypeScript file named 'first-automation.ts' using Node.js with the tsx runner. Ensure you have Node.js and tsx installed.

```bash
npx tsx first-automation.ts
```

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

### Multi-Step Workflow Goal Example

Source: https://docs.mino.ai/key-concepts/goals

This example illustrates how to define a sequence of actions for the TinyFish Web Agent using a multi-step workflow described in natural language. It includes logging in, navigating to a specific page, and extracting information, demonstrating the agent's ability to handle complex, sequential tasks.

```text
1. Login with email "user@example.com" and password "pass123"
2. Navigate to the dashboard
3. Extract account balance
```

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

### Run First Workflow with Python

Source: https://docs.mino.ai/quick-start

This Python script demonstrates how to execute a web automation task via the TinyFish API. It utilizes the requests library to send a POST request and process the SSE stream, retrieving the API key from environment variables.

```python
# first_automation.py
import json
import os
from dotenv import load_dotenv
import requests

load_dotenv()

response = requests.post(
    "https://agent.tinyfish.ai/v1/automation/run-sse",
    headers={
        "X-API-Key": os.getenv("TINYFISH_API_KEY"),
        "Content-Type": "application/json",
    },
    json={
        "url": "https://scrapeme.live/shop",  // Target website to automate
        "goal": "Extract the first 2 product names and prices",  // Natural language instruction
    },
    stream=True,  // Enable SSE streaming
)

# Read the SSE stream
for line in response.iter_lines():
    if line:
        line_str = line.decode("utf-8")
        if line_str.startswith("data: "):
            event = json.loads(line_str[6:])
            print(event)  # Print each event as it arrives
```

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

### Python - Streaming API

Source: https://docs.mino.ai/install-with-ai

Example code for integrating the TinyFish Web Agent using the streaming API endpoint (`/run-sse`) in Python. This method provides real-time progress updates.

```APIDOC
## Python - Streaming API

### Description
This Python function utilizes the `/run-sse` endpoint to perform web automation with real-time progress feedback. It's ideal for monitoring the automation process.

### Method
`POST`

### Endpoint
`/v1/automation/run-sse`

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - A natural language description of the task to perform.

### Request Example
```json
{
  "url": "https://example.com/products",
  "goal": "Extract all product names and prices as JSON"
}
```

### Response
#### Success Response (200)
- **resultJson** (object) - The structured JSON result of the automation task upon completion.

#### Response Example
```json
{
  "type": "COMPLETE",
  "status": "COMPLETED",
  "resultJson": [
    {
      "name": "Product A",
      "price": "$10.00"
    },
    {
      "name": "Product B",
      "price": "$20.00"
    }
  ]
}
```

### Code
```python
import os
import json
from dotenv import load_dotenv
import requests

load_dotenv()

def run_automation(url: str, goal: str):
    response = requests.post(
        "https://agent.tinyfish.ai/v1/automation/run-sse",
        headers={
            "X-API-Key": os.environ["TINYFISH_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"url": url, "goal": goal},
        stream=True,
    )

    for line in response.iter_lines():
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                event = json.loads(line[6:])
                if event["type"] == "PROGRESS":
                    print(f"Action: {event.get('purpose', '')}")
                elif event["type"] == "COMPLETE":
                    if event["status"] == "COMPLETED":
                        return event.get("resultJson")
                    raise Exception(event.get("error", {}).get("message", "Failed"))

# Example usage
# products = run_automation(
#     "https://example.com/products",
#     "Extract all product names and prices as JSON"
# )
# print(products)
```
```

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

### Python - Synchronous API

Source: https://docs.mino.ai/install-with-ai

Example code for integrating the TinyFish Web Agent using the synchronous API endpoint (`/run`) in Python. This method waits for the task to complete before returning the result.

```APIDOC
## Python - Synchronous API

### Description
This Python function uses the synchronous `/run` endpoint to execute web automation tasks. The function will block until the task is finished and then return the result.

### Method
`POST`

### Endpoint
`/v1/automation/run`

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - A natural language description of the task to perform.

### Request Example
```json
{
  "url": "https://example.com/login",
  "goal": "Log in to the website using provided credentials"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the automation task.

#### Response Example
```json
{
  "status": "COMPLETED",
  "result": {
    "message": "Login successful"
  }
}
```

### Code
```python
import os
from dotenv import load_dotenv
import requests

load_dotenv()

def run_automation(url: str, goal: str):
    response = requests.post(
        "https://agent.tinyfish.ai/v1/automation/run",
        headers={
            "X-API-Key": os.environ["TINYFISH_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"url": url, "goal": goal},
    )
    run = response.json()
    if run["status"] == "COMPLETED":
        return run["result"]
    raise Exception(run.get("error", {}).get("message", "Automation failed"))

# Example usage
# login_result = run_automation(
#     "https://example.com/login",
#     "Log in to the website using provided credentials"
# )
# print(login_result)
```
```

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

### Form Filling Goal Example

Source: https://docs.mino.ai/key-concepts/goals

This example shows how to use the 'goal' parameter to automate form submission. It instructs the TinyFish Web Agent to fill in a contact form with provided details and then click the submit button. This showcases the agent's capability to interact with web elements based on natural language commands.

```text
Fill the contact form with name "John Doe" and email "john@example.com", then click Submit.
```

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

### Run First Workflow with JavaScript/TypeScript

Source: https://docs.mino.ai/quick-start

This JavaScript code snippet shows how to programmatically run a web automation task using the TinyFish API. It handles API key retrieval from environment variables and streams the Server-Sent Events (SSE) response.

```javascript
import 'dotenv/config'

const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-sse", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TINYFISH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://scrapeme.live/shop",  // Target website to automate
    goal: "Extract the first 2 product names and prices",  // Natural language instruction
  }),
});

// Read the SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));  // Print each event as it arrives
}
```

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

### Install TinyFish MCP Server for AI Assistants (Bash)

Source: https://docs.mino.ai/install-with-ai

Installs the TinyFish MCP server using npx for various AI clients. This command fetches the latest version and specifies the client for integration. Ensure you have Node.js and npm installed.

```bash
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
```

```bash
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor
```

```bash
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client windsurf
```

```bash
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude
```

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

### Data Extraction Goal Example

Source: https://docs.mino.ai/key-concepts/goals

This example demonstrates how to instruct the TinyFish Web Agent to extract specific data points (product name, price, stock status) from a webpage and return them in JSON format. It highlights the agent's ability to parse natural language requests for structured data retrieval.

```text
Extract product name, price, and stock status. Return as JSON.
```

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

### Configure Anti-Detection Mode with TypeScript

Source: https://docs.mino.ai/install-with-ai

This TypeScript example demonstrates how to configure the Mino AI API request for sites with bot protection. It includes enabling stealth mode and configuring proxy settings with a specified country code.

```typescript
body: JSON.stringify({
  url: "https://protected-site.com",
  goal: "Extract pricing data",
  browser_profile: "stealth",
  proxy_config: {
    enabled: true,
    country_code: "US",  // Also: GB, CA, DE, FR, JP, AU
  },
})
```

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

### SSE Event Stream Response Example

Source: https://docs.mino.ai/api-reference

This example shows the format of the Server-Sent Events (SSE) stream received from the `/v1/automation/run-sse` endpoint. The stream contains various event types such as STARTED, STREAMING_URL, PROGRESS, and COMPLETE, each with a run ID and timestamp. The COMPLETE event includes the final status and result JSON.

```text
"data: {\"type\":\"STARTED\",\"runId\":\"run_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}

data: {\"type\":\"STREAMING_URL\",\"runId\":\"run_123\",\"streamingUrl\":\"https://...\",\"timestamp\":\"...\"}

data: {\"type\":\"PROGRESS\",\"runId\":\"run_123\",\"purpose\":\"Clicking submit button\",\"timestamp\":\"...\"}

data: {\"type\":\"COMPLETE\",\"runId\":\"run_123\",\"status\":\"COMPLETED\",\"resultJson\":{...},\"timestamp\":\"...\"}"
```

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

### MCP Integration Setup

Source: https://docs.mino.ai/mcp-integration

Instructions for setting up TinyFish Web Agent with different MCP-compatible AI assistants.

```APIDOC
## MCP Integration Setup

### Claude Desktop (macOS/Windows)
Add the following to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}
```

Restart Claude Desktop and authenticate via OAuth.

### Cursor
Add the following to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}
```

### Claude Code
Use the following command:

```bash
claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
```
```

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

### POST /v1/automation/run

Source: https://docs.mino.ai/install-with-ai

Initiates a web automation task. This endpoint takes a URL and a goal, and returns the result of the automation.

```APIDOC
## POST /v1/automation/run

### Description
Initiates a web automation task. This endpoint takes a URL and a goal, and returns the result of the automation. It supports anti-detection features like stealth mode and proxy configuration.

### Method
POST

### Endpoint
https://agent.tinyfish.ai/v1/automation/run

### Parameters
#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - The specific task to perform on the website.
- **browser_profile** (string) - Optional - Specifies the browser profile to use, e.g., "stealth" for anti-detection.
- **proxy_config** (object) - Optional - Configuration for using a proxy server.
  - **enabled** (boolean) - Required - Whether to enable the proxy.
  - **country_code** (string) - Optional - The country code for the proxy (e.g., US, GB, CA, DE, FR, JP, AU).

### Request Example
```json
{
  "url": "https://protected-site.com",
  "goal": "Extract pricing data",
  "browser_profile": "stealth",
  "proxy_config": {
    "enabled": true,
    "country_code": "US"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the automation task (e.g., "COMPLETED").
- **result** (any) - The result of the automation task if the status is "COMPLETED".
- **error** (object) - Contains error details if the task failed.
  - **message** (string) - A description of the error.

#### Response Example
```json
{
  "status": "COMPLETED",
  "result": [
    {
      "product_name": "Example Product",
      "price": "$19.99"
    }
  ]
}
```

#### Error Response (e.g., 400, 500)
```json
{
  "status": "FAILED",
  "error": {
    "message": "An error occurred during automation."
  }
}
```
```

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

### TypeScript - Streaming API

Source: https://docs.mino.ai/install-with-ai

Example code for integrating the TinyFish Web Agent using the streaming API endpoint (`/run-sse`) in TypeScript. This method provides real-time progress updates.

```APIDOC
## TypeScript - Streaming API

### Description
This endpoint (`/run-sse`) allows you to run web automation tasks and receive real-time progress updates. It's recommended for interactive or long-running tasks.

### Method
`POST`

### Endpoint
`/v1/automation/run-sse`

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - A natural language description of the task to perform.

### Request Example
```json
{
  "url": "https://example.com/products",
  "goal": "Extract all product names and prices as JSON"
}
```

### Response
#### Success Response (200)
- **resultJson** (object) - The structured JSON result of the automation task upon completion.

#### Response Example
```json
{
  "type": "COMPLETE",
  "status": "COMPLETED",
  "resultJson": [
    {
      "name": "Product A",
      "price": "$10.00"
    },
    {
      "name": "Product B",
      "price": "$20.00"
    }
  ]
}
```

### Code
```typescript
import 'dotenv/config'

async function runAutomation(url: string, goal: string) {
  const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-sse", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TINYFISH_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url, goal }),
  });

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const event = JSON.parse(line.slice(6));

        if (event.type === "PROGRESS") {
          console.log(`Action: ${event.purpose}`);
        } else if (event.type === "COMPLETE") {
          if (event.status === "COMPLETED") {
            return event.resultJson;
          }
          throw new Error(event.error?.message || "Automation failed");
        }
      }
    }
  }
}

// Example usage
// const products = await runAutomation(
//   "https://example.com/products",
//   "Extract all product names and prices as JSON"
// );
// console.log(products);
```
```

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

### TypeScript - Synchronous API

Source: https://docs.mino.ai/install-with-ai

Example code for integrating the TinyFish Web Agent using the synchronous API endpoint (`/run`) in TypeScript. This method waits for the task to complete before returning the result.

```APIDOC
## TypeScript - Synchronous API

### Description
This endpoint (`/run`) executes web automation tasks and returns the result only after the task is completed. It's suitable for simpler, non-interactive automation.

### Method
`POST`

### Endpoint
`/v1/automation/run`

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - A natural language description of the task to perform.

### Request Example
```json
{
  "url": "https://example.com/login",
  "goal": "Log in to the website using provided credentials"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the automation task.

#### Response Example
```json
{
  "status": "COMPLETED",
  "result": {
    "message": "Login successful"
  }
}
```

### Code
```typescript
import 'dotenv/config'

async function runAutomation(url: string, goal: string) {
  const response = await fetch("https://agent.tinyfish.ai/v1/automation/run", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TINYFISH_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url, goal }),
  });

  const run = await response.json();
  if (run.status === "COMPLETED") return run.result;
  throw new Error(run.error?.message || "Automation failed");
}

// Example usage
// const loginResult = await runAutomation(
//   "https://example.com/login",
//   "Log in to the website using provided credentials"
// );
// console.log(loginResult);
```
```

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

### Streaming API Call with /run-sse Endpoint (Start)

Source: https://docs.mino.ai/key-concepts/endpoints

This snippet shows the initial request to the /run-sse endpoint, which starts an automation and prepares to stream updates. It sets up the POST request with necessary headers and the automation's goal.

```typescript
const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-sse", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TINYFISH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    goal: "Extract all product data",
  }),
});
```

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

### SearchTinyFishWebAgent

Source: https://docs.mino.ai/mcp

Searches the TinyFish Web Agent knowledge base for relevant information, code examples, API references, and guides. Use this tool when you need to answer questions about TinyFish Web Agent, find specific documentation, understand how features work, or locate implementation details. The search returns contextual content with titles and direct links to the documentation pages.

```APIDOC
## POST /search

### Description
Searches the TinyFish Web Agent knowledge base.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
None

#### Request Body
- **query** (string) - Required - A query to search the content with.

### Request Example
```json
{
  "query": "How to use the authentication API?"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results, each containing a title, content snippet, and URL.

#### Response Example
```json
{
  "results": [
    {
      "title": "TinyFish Authentication API Guide",
      "content": "This guide explains how to authenticate with the TinyFish API...",
      "url": "https://docs.tinyfish.ai/auth"
    }
  ]
}
```
```

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

### Start TinyFish Web Agent run asynchronously

Source: https://docs.mino.ai/examples/bulk-requests-async

This endpoint allows you to start a TinyFish Web Agent run asynchronously. You submit a task and receive a run ID, which you can later use to check the status and retrieve results.

```APIDOC
## POST /v1/run-async

### Description
Starts a TinyFish Web Agent run asynchronously. This is useful for long-running tasks or when you need to submit multiple tasks without waiting for each to complete.

### Method
POST

### Endpoint
/v1/run-async

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the website to process.
- **goal** (string) - Required - The objective for the agent, e.g., "Extract product information".

### Request Example
```json
{
  "url": "https://example.com/page1",
  "goal": "Extract product info"
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the asynchronous run.

#### Response Example
```json
{
  "run_id": "run_abc123xyz"
}
```
```

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

### POST /v1/automation/run-sse

Source: https://docs.mino.ai/install-with-ai

Initiates a web automation task using Server-Sent Events (SSE). This is useful for real-time updates on the automation progress.

```APIDOC
## POST /v1/automation/run-sse

### Description
Initiates a web automation task and streams results using Server-Sent Events (SSE). This endpoint is suitable for long-running tasks where real-time feedback is desired.

### Method
POST

### Endpoint
https://agent.tinyfish.ai/v1/automation/run-sse

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL of the website to automate.
- **goal** (string) - Required - The specific task to perform on the website.

### Request Example
```bash
curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "url": "https://scrapeme.live/shop", \
    "goal": "Extract the first 3 product names and prices" \
  }'
```

### Response
#### Success Response (200)
This endpoint streams data over SSE. The exact format of the streamed data will depend on the automation task and may include progress updates and final results.

#### Response Example (SSE Stream)
```
data: {"progress": "50%"}

data: {"result": [{"name": "Product A", "price": "$10"}, {"name": "Product B", "price": "$20"}]}

```

#### Error Response (e.g., 400, 500)
Errors will typically be communicated via standard HTTP error codes and potentially within the SSE stream if the connection is established.
```

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

### POST /v1/automation/run-async

Source: https://docs.mino.ai/api-reference/automation/start-automation-asynchronously

Starts an automation task asynchronously. This endpoint enqueues a task and returns a run ID immediately, allowing for separate polling of results.

```APIDOC
## POST /v1/automation/run-async

### Description
Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.

### Method
POST

### Endpoint
/v1/automation/run-async

### Parameters
#### Request Body
- **url** (string) - Required - Target website URL to automate
- **goal** (string) - Required - Natural language description of what to accomplish on the website
- **browser_profile** (string) - Optional - Browser profile for execution. Enum: `lite`, `stealth`. Defaults to `lite`.
- **proxy_config** (object) - Optional - Proxy configuration
  - **enabled** (boolean) - Required - Enable proxy for this automation run
  - **country_code** (string) - Optional - ISO 3166-1 alpha-2 country code for proxy location. Enum: `US`, `GB`, `CA`, `DE`, `FR`, `JP`, `AU`.

### Request Example
```json
{
  "url": "https://example.com",
  "goal": "Find the pricing page and extract all plan details",
  "browser_profile": "lite",
  "proxy_config": {
    "enabled": true,
    "country_code": "US"
  }
}
```

### Response
#### Success Response (200)
- **run_id** (string) - Unique identifier for the created automation run. Null if creation failed.
- **error** (object) - Error details. Null if successful.
  - **message** (string) - Error message if run creation failed.

#### Response Example
```json
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": null
}
```

#### Error Response (400)
- **error** (object)
  - **code** (string) - Error code. Enum: `MISSING_API_KEY`, `INVALID_API_KEY`, `INVALID_INPUT`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`, `UNAUTHORIZED`.
  - **message** (string) - Error message.
```

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

### MCP Integration Setup

Source: https://docs.mino.ai/mcp-integration/index

Configuration snippets for integrating TinyFish Web Agent with Claude Desktop, Cursor, and Claude Code.

```APIDOC
## MCP Integration Setup

### Claude Desktop (macOS/Windows)

Add the following to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}
```

Restart Claude Desktop and authenticate via OAuth.

### Cursor

Add the following to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}
```

### Claude Code

Use the following command:

```bash
claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
```
```

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

### POST /run_web_automation_async

Source: https://docs.mino.ai/mcp-integration/index

Starts web automation asynchronously and returns a run ID immediately. Ideal for long-running tasks where real-time progress is not required.

```APIDOC
## POST /run_web_automation_async

### Description
Starts automation asynchronously and returns a `run_id` immediately. Use this for long-running tasks where you don't need real-time progress.

### Method
POST

### Endpoint
/run_web_automation_async

### Parameters
#### Query Parameters

* **url** (string) - Required - Target website URL
* **goal** (string) - Required - Natural language description of what to do
* **browser_profile** (string) - Optional - `lite` (default) or `stealth` for anti-detection
* **proxy_config** (object) - Optional - Proxy settings with `enabled` and `country_code`

### Request Example
```json
{
  "url": "https://store.com",
  "goal": "Extract all products"
}
```

### Response
#### Success Response (200)

* **run_id** (string) - The ID of the asynchronous run.
* **error** (object) - An error object if the run failed to start.

#### Response Example
```json
{
  "run_id": "abc123-xyz789",
  "error": null
}
```
```

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

### Example of Goal Succeeded Result (JSON)

Source: https://docs.mino.ai/key-concepts/runs

An example JSON structure for a run where the infrastructure worked and the user's goal was successfully achieved, indicated by a successful status within the result field.

```json
{
  "status": "COMPLETED",
  "result": {
    "products": [
      { "name": "Widget", "price": 29.99 }
    ]
  }
}
```

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

### Proxy Configuration in TypeScript

Source: https://docs.mino.ai/faq

Illustrates how to configure proxy settings for web automation using TinyFish Web Agent. This example shows enabling the proxy and specifying a country code.

```typescript
{
  proxy_config: {
    enabled: true,
    country_code: "US"
  }
}
```

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

### run_web_automation_async API

Source: https://docs.mino.ai/mcp-integration

Starts automation asynchronously and returns a run_id immediately. Use this for long-running tasks.

```APIDOC
## POST /run_web_automation_async

### Description
Starts automation asynchronously and returns a `run_id` immediately. Use this for long-running tasks where you don't need real-time progress.

### Method
POST

### Endpoint
/run_web_automation_async

### Parameters
#### Query Parameters
- **url** (string) - Required - Target website URL
- **goal** (string) - Required - Natural language description of what to do
- **browser_profile** (string) - Optional - `lite` (default) or `stealth` for anti-detection
- **proxy_config** (object) - Optional - Proxy settings with `enabled` and `country_code`

### Request Example
```json
{
  "url": "https://store.com",
  "goal": "Extract all products"
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The ID of the asynchronous run
- **error** (object | null) - Null if successful

#### Response Example
```json
{
  "run_id": "abc123-...",
  "error": null
}
```
```

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

### Start Automation Asynchronously

Source: https://docs.mino.ai/api-reference/automation/start-automation-asynchronously

Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.

```APIDOC
## POST /websites/mino_ai/automations/start

### Description
Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.

### Method
POST

### Endpoint
/websites/mino_ai/automations/start

### Parameters
#### Query Parameters
None

#### Request Body
- **automation_type** (string) - Required - The type of automation to run.
- **parameters** (object) - Optional - Parameters specific to the automation type.

### Request Example
```json
{
  "automation_type": "long_running_process",
  "parameters": {
    "input_data": "some_data"
  }
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the automation run.

#### Response Example
```json
{
  "run_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

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

### Example cURL Request with API Key

Source: https://docs.mino.ai/error-codes

Illustrates how to include the necessary API key in the request headers when using cURL. This is a common solution for errors related to missing or invalid API keys.

```bash
curl -H "X-API-Key: $TINYFISH_API_KEY" ...
```

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

### Expected SSE Output from Workflow

Source: https://docs.mino.ai/quick-start

This is an example of the Server-Sent Events (SSE) output you should expect to see in your terminal after running a TinyFish automation workflow. It includes status updates and the final JSON result.

```bash
{'type': 'STARTED', 'runId': 'abc123'}
{'type': 'STREAMING_URL', 'runId': 'abc123', 'streamingUrl': 'https://stream.mino.ai/session/abc123'}
{'type': 'PROGRESS', 'runId': 'abc123', 'purpose': 'Visit the page to extract product information'}
{'type': 'PROGRESS', 'runId': 'abc123', 'purpose': 'Check for product information on the page'}
{'type': 'COMPLETE', 'runId': 'abc123', 'status': 'COMPLETED', 'resultJson': {
  "products": [
    { "name": "Bulbasaur", "price": "$63.00" },
    { "name": "Ivysaur", "price": "$87.00" },
  ]
}}
```

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

### Retry with Stealth Mode

Source: https://docs.mino.ai/common-patterns

Some sites block automated requests. Start with lite mode for speed, then automatically retry with stealth mode if you get blocked.

```APIDOC
## Retry with Stealth Mode

### Description
Some websites block automated requests. This pattern demonstrates how to first attempt extraction using a standard "lite" browser profile and then automatically retry with a "stealth" profile if the initial attempt is blocked. It also includes configuration for proxy usage in stealth mode.

### Method
POST (implicitly used by `runAutomation`)

### Endpoint
/v1/automation/run (or similar, depending on `runAutomation` implementation)

### Parameters (for `runAutomation`)
#### Query Parameters
- **url** (string) - Required - The URL of the website.
- **goal** (string) - Required - The objective for the automation.
- **browser_profile** (string) - Optional - Specifies the browser profile to use. Options include "lite" (faster) and "stealth" (more robust against blocking).
- **proxy_config** (object) - Optional - Configuration for using a proxy server. 
  - **enabled** (boolean) - Required - Whether to enable proxy.
  - **country_code** (string) - Optional - The country code for the proxy server (e.g., "US").

### Request Example (Conceptual)
```typescript
async function extractWithFallback(url: string, goal: string) {
  // Try standard mode first
  let result = await runAutomation(url, goal, { browser_profile: "lite" });

  if (result.status === "FAILED" && result.error?.message.includes("blocked")) {
    // Retry with stealth mode
    result = await runAutomation(url, goal, {
      browser_profile: "stealth",
      proxy_config: { enabled: true, country_code: "US" },
    });
  }

  return result;
}
```

### Response (Conceptual)
Returns the result of the `runAutomation` call, which could be a success or failure status with associated data or error messages.
```

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

### Documentation Index

Source: https://docs.mino.ai/api-reference/runs/get-run-by-id

Fetch the complete documentation index for Mino AI LLMs.

```APIDOC
## GET /websites/mino_ai/documentation/index

### Description
Fetch the complete documentation index for Mino AI LLMs. This index can be used to discover all available documentation pages.

### Method
GET

### Endpoint
/websites/mino_ai/documentation/index

### Parameters
None

### Response
#### Success Response (200)
- **documentation_url** (string) - The URL to the documentation index file.

#### Response Example
```json
{
  "documentation_url": "https://docs.mino.ai/llms.txt"
}
```
```

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

### Run Automation Task with Python

Source: https://docs.mino.ai/install-with-ai

This Python snippet shows how to send a POST request to the Mino AI automation API to run a task. It includes setting the API key via environment variables, specifying the URL and goal, and handling the response, including error checking.

```python
import requests
import os

url = "your_target_url"
goal = "your_specific_goal"

response = requests.post(
    "https://agent.tinyfish.ai/v1/automation/run",
    headers={
        "X-API-Key": os.environ["TINYFISH_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"url": url, "goal": goal},
)
run = response.json()
if run["status"] == "COMPLETED":
    return run["result"]
raise Exception(run.get("error", {}).get("message", "Failed"))
```

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

### Example of Goal Failed Result (JSON)

Source: https://docs.mino.ai/key-concepts/runs

An example JSON structure for a run where the infrastructure worked, but the user's goal could not be achieved, indicated by a failure status within the result field.

```json
{
  "status": "COMPLETED",
  "result": {
    "status": "failure",
    "reason": "Could not find any products on the page"
  }
}
```

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

### POST /v1/automation/run

Source: https://docs.mino.ai/common-patterns

Use the synchronous endpoint for quick, one-off extractions where you need the result immediately.

```APIDOC
## POST /v1/automation/run

### Description
Use the synchronous endpoint for quick, one-off extractions where you need the result immediately.

### Method
POST

### Endpoint
/v1/automation/run

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the website to extract data from.
- **goal** (string) - Required - The description of the data to extract. For example: "Extract all product names and prices. Return as JSON."

#### Request Body
This endpoint does not use a request body. Parameters are sent as query parameters.

### Request Example
```
https://agent.tinyfish.ai/v1/automation/run?url=https://example.com/products&goal=Extract%20all%20product%20names%20and%20prices.%20Return%20as%20JSON.
```

### Response
#### Success Response (200)
- **status** (string) - The status of the extraction task (e.g., "COMPLETED").
- **result** (object) - The extracted data in JSON format.

#### Response Example
```json
{
  "status": "COMPLETED",
  "result": {
    "products": [
      {
        "name": "Product A",
        "price": "$10.00"
      },
      {
        "name": "Product B",
        "price": "$20.00"
      }
    ]
  }
}
```
```

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

### Get run by ID

Source: https://docs.mino.ai/api-reference/runs/get-run-by-id

Retrieve detailed information about a specific automation run using its unique identifier.

```APIDOC
## GET /websites/mino_ai/runs/{run_id}

### Description
Get detailed information about a specific automation run by its ID.

### Method
GET

### Endpoint
/websites/mino_ai/runs/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the automation run.

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier of the automation run.
- **status** (string) - The current status of the run (e.g., 'completed', 'failed', 'running').
- **start_time** (string) - The timestamp when the run started.
- **end_time** (string) - The timestamp when the run ended.
- **results** (object) - An object containing the results of the automation run.

#### Response Example
```json
{
  "run_id": "run_abc123",
  "status": "completed",
  "start_time": "2023-10-27T10:00:00Z",
  "end_time": "2023-10-27T10:05:00Z",
  "results": {
    "output": "Automation completed successfully."
  }
}
```
```

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

### Quick Test Automation Run with cURL

Source: https://docs.mino.ai/install-with-ai

This cURL command provides a quick way to test the Mino AI automation API's Server-Sent Events (SSE) endpoint. It sends a POST request with a target URL and a specific goal, demonstrating a basic interaction.

```bash
curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "url": "https://scrapeme.live/shop", \
    "goal": "Extract the first 3 product names and prices" \
  }'
```

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

### Get Run by ID API

Source: https://docs.mino.ai/examples/bulk-requests-async

Check the status and retrieve the results of a specific run using its unique ID.

```APIDOC
## GET /v1/runs/:id

### Description
Retrieves the details of a specific run, including its status, results, or error messages if it failed.

### Method
GET

### Endpoint
/v1/runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the run.

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the run.
- **status** (string) - The current status of the run (e.g., PENDING, RUNNING, COMPLETED, FAILED, CANCELLED).
- **result** (object) - The result of the run (if completed successfully).
- **error** (object) - Details about the error if the run failed.

#### Response Example
```json
{
  "run_id": "run_abc123xyz",
  "status": "COMPLETED",
  "result": {
    "extracted_data": "..."
  }
}
```

#### Error Response (404)
- **message** (string) - Indicates that the run ID was not found.

#### Error Response Example
```json
{
  "message": "Run with ID run_nonexistent789 not found."
}
```
```

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

### GET /list_runs

Source: https://docs.mino.ai/mcp-integration/index

Lists your automation runs with optional filtering and pagination capabilities.

```APIDOC
## GET /list_runs

### Description
Lists your automation runs with optional filtering and pagination.

### Method
GET

### Endpoint
/list_runs

### Parameters
#### Query Parameters

* **status** (string) - Optional - Filter by status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
* **cursor** (string) - Optional - Pagination cursor from previous response
* **limit** (number) - Optional - Max results (1-100, default 20)

### Response
#### Success Response (200)

* **runs** (array) - A list of automation runs.
* **next_cursor** (string) - A cursor for fetching the next page of results.

#### Response Example
```json
{
  "runs": [
    {
      "run_id": "abc123-xyz789",
      "status": "COMPLETED",
      "goal": "Extract all products"
    },
    {
      "run_id": "def456-uvw012",
      "status": "RUNNING",
      "goal": "Scrape headlines"
    }
  ],
  "next_cursor": "some_cursor_string"
}
```
```
Tokens:
Raw