TinyFish Web Agent

https://docs.tinyfish.ai
Admin
TinyFish Web Agent is an AI-powered web automation platform that converts natural language...
Tokens:427,924
Snippets:2,927
Trust Score:7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start a setup session with curl

Source: https://docs.tinyfish.ai/agent-api/browser-context-profiles

POST to /v1/profiles/{profile_id}/setup-session to start a setup browser. Requires X-API-Key header. The request body includes url (required) and timeout_seconds (optional).

```bash
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "timeout_seconds": 900
  }'
```

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

### Start a setup session for a profile

Source: https://docs.tinyfish.ai/key-concepts/browser-context-profiles

Starts a setup session for the profile with ID 'prof_abc123def4567890', targeting the login URL. The response includes session_id, cdp_url, base_url, timeout_seconds, and expires_at.

```bash
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/login" }'
```

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

### API: Create profile and start setup session

Source: https://docs.tinyfish.ai/llms-full.txt

Create a Browser Context Profile via the TinyFish API, start a setup session, and connect your own Playwright/Puppeteer/CDP controller to the returned cdp_url. Sign in to the target site, then save the session with the returned session_id. The hosted setup UI is only a manual helper.

```text
Create the profile, start a setup session, connect your own Playwright/Puppeteer/CDP controller to `cdp_url`, sign in, then save it with the returned `session_id`. The hosted setup UI is only a manual helper.
```

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

### Quick Start TinyFish CLI

Source: https://docs.tinyfish.ai/cli

Quick start: installs the CLI, sets the API key, and runs a browser automation agent to extract product data from a URL.

```bash
npm install -g @tiny-fish/cli@latest
export TINYFISH_API_KEY="sk-tinyfish-..."
tinyfish agent run --url "https://example.com" "Extract product data. Return JSON."

```

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

### Successful response example for saving a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/save-a-profile-setup-session

Example 200 response showing domains updated, cookie count, and sign-in status.

```json
{
  "domains_updated": [
    "example.com"
  ],
  "domains_failed": [],
  "cookie_count": 12,
  "domains_skipped": {
    "cookies_skipped": [],
    "local_storage_skipped": [],
    "session_storage_skipped": [],
    "blob_too_large": []
  },
  "pages_captured": 1,
  "target_reads_skipped": 0,
  "cleanup_failed": false,
  "cleanup_kind": "post_save",
  "signed_in_sites": [
    "github.com"
  ],
  "sign_in": {
    "site": "github.com",
    "status": "recorded"
  },
  "user_confirmed_sites": {
    "recorded": [
      "facebook.com"
    ],
    "rejected": [
      {
        "site": "notion.so",
        "reason": "not_saved"
      }
    ]
  }
}
```

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

### Go example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses the net/http package to send a GET request with the X-API-Key header. Reads and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/profiles/{profileId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### POST /v1/profiles/{profileId}/setup-session

Source: https://docs.tinyfish.ai/agent-api/browser-context-profiles

Start an interactive setup browser session for a profile.

```APIDOC
## POST /v1/profiles/{profileId}/setup-session

### Description
Start an interactive setup browser session.

### Method
POST

### Endpoint
/v1/profiles/{profileId}/setup-session

### Parameters
#### Path Parameters
- **profileId** (string) - Required - The unique identifier of the profile.
```

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

### Quick Start: install, set API key, run agent

Source: https://docs.tinyfish.ai/llms-full.txt

Installs the CLI, sets the API key via environment variable, and runs an agent against a URL. The agent extracts product data and returns JSON.

```bash
npm install -g @tiny-fish/cli@latest
export TINYFISH_API_KEY="sk-tinyfish-..."
tinyfish agent run --url "https://example.com" "Extract product data. Return JSON."
```

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

### Go example to save a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/save-a-profile-setup-session

Uses net/http to POST the session data. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/profiles/{profileId}/save"

	payload := strings.NewReader("{\n  \"session_id\": \"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"signed_in_sites\": [\n    \"facebook.com\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Ruby example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses Net::HTTP to send a GET request with the X-API-Key header. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://agent.tinyfish.ai/v1/profiles/{profileId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

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

### Go example for step HTML snapshot

Source: https://docs.tinyfish.ai/api-reference/runs/get-step-html-snapshot

Uses net/http to GET the HTML snapshot. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/runs/{id}/steps/{stepId}/html"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### POST /v1/profiles/{profile_id}/setup-session

Source: https://docs.tinyfish.ai/agent-api/browser-context-profiles

Starts a setup browser session for a profile, returning a CDP URL to connect to for automating login.

```APIDOC
## POST /v1/profiles/{profile_id}/setup-session

### Description
Starts a setup browser session for the specified profile, returning a CDP URL and base URL for automation.

### Method
POST

### Endpoint
https://agent.tinyfish.ai/v1/profiles/{profile_id}/setup-session

### Parameters
#### Path Parameters
- `profile_id` (string) - Required - The ID of the profile.

#### Request Body
- `url` (string) - Required - The URL to navigate to in the setup browser.
- `timeout_seconds` (integer) - Optional - Timeout for the session in seconds.

### Request Example
```json
{
  "url": "https://app.example.com/login",
  "timeout_seconds": 900
}
```

### Response
#### Success Response (200)
- `session_id` (string) - Session ID.
- `cdp_url` (string) - WebSocket URL for CDP connection.
- `base_url` (string) - Base URL.
- `timeout_seconds` (integer) - Timeout in seconds.
- `expires_at` (string) - Expiration timestamp.

#### Response Example
```json
{
  "session_id": "sess_123",
  "cdp_url": "wss://...",
  "base_url": "https://...",
  "timeout_seconds": 900,
  "expires_at": "2026-06-04T18:15:00.000Z"
}
```
```

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

### Setup session response

Source: https://docs.tinyfish.ai/agent-api/browser-context-profiles

Example JSON response from the setup-session endpoint, containing session_id, cdp_url, base_url, timeout_seconds, and expires_at.

```json
{
  "session_id": "sess_123",
  "cdp_url": "wss://...",
  "base_url": "https://...",
  "timeout_seconds": 900,
  "expires_at": "2026-06-04T18:15:00.000Z"
}
```

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

### Go example for get run by ID

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

Uses the net/http package to fetch run details. Requires an API key in the X-API-Key header.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/runs/{id}?screenshots=url&html=url"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Ruby example for step HTML snapshot

Source: https://docs.tinyfish.ai/api-reference/runs/get-step-html-snapshot

Uses net/http to GET the HTML snapshot. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://agent.tinyfish.ai/v1/runs/{id}/steps/{stepId}/html")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

```

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

### List vault items with Go

Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

Go example using net/http to GET /v1/vault/items. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/vault/items"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### POST /v1/automation/run-sse - example event stream

Source: https://docs.tinyfish.ai/agent-api/reference

Shows the SSE event stream from the /run-sse endpoint. Events include STARTED, STREAMING_URL, PROGRESS, HEARTBEAT, and COMPLETE. SSE streams do not support Last-Event-ID reconnection; recover by polling GET /v1/runs/{run_id} until terminal status.

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

data: {"type":"STREAMING_URL","run_id":"run_123","streaming_url":"https://...","timestamp":"..."}

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

data: {"type":"COMPLETE","run_id":"run_123","status":"COMPLETED","result":{...},"timestamp":"..."}
```

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

### tinyfish wallet status --pretty - example

Source: https://docs.tinyfish.ai/cli/commands

Example of using the `--pretty` flag to get human-readable output.

```bash
tinyfish wallet status --pretty

```

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

### Create a profile with sign-in link

Source: https://docs.tinyfish.ai/cli/commands

Creates a Browser Context Profile and returns a setup_url for the user to sign in. The link opens a TinyFish page with a live browser and a Save profile button. At a terminal, the CLI opens the link for you. For agents: give the user setup_url, never ask for their password, and confirm the save with tinyfish profile list.

```bash
tinyfish profile create --name "my-github" --site github.com

```

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

### Go: Create a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

Uses net/http to POST the payload to the setup-session endpoint. Requires an API key in the X-API-Key header.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session"

	payload := strings.NewReader("{\n  \"url\": \"https://www.tinyfish.ai\",\n  \"timeout_seconds\": 300\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### POST /v1/profiles/{profileId}/setup-session

Source: https://docs.tinyfish.ai/llms-full.txt

Starts a temporary setup browser for a Browser Context Profile. Returns session_id, cdp_url, base_url, timeout_seconds, and expires_at for connecting automation clients.

```APIDOC
## POST /v1/profiles/{profileId}/setup-session

### Description
Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session is cancelled or times out.

### Method
POST

### Endpoint
/v1/profiles/{profileId}/setup-session

### Parameters
#### Path Parameters
- **profileId** (string) - Required - The ID of the Browser Context Profile.

### Response
#### Success Response
- **session_id** (string) - The session identifier.
- **cdp_url** (string) - The URL for connecting a CDP client.
- **base_url** (string) - The base URL for the setup browser.
- **timeout_seconds** (integer) - The timeout duration in seconds.
- **expires_at** (string) - The expiration timestamp of the session.

```

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

### Java Unirest example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses the Unirest library to send a GET request with the X-API-Key header. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://agent.tinyfish.ai/v1/profiles/{profileId}")
  .header("X-API-Key", "<api-key>")
  .asString();
```

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

### Python requests example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses the requests library to perform a GET request with the X-API-Key header. Prints the response text.

```python
import requests

url = "https://agent.tinyfish.ai/v1/profiles/{profileId}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

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

### PHP cURL example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses PHP cURL to send a GET request with the X-API-Key header. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agent.tinyfish.ai/v1/profiles/{profileId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

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

### JavaScript fetch example to get a browser context profile

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

Uses the fetch API to send a GET request with the X-API-Key header. Logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://agent.tinyfish.ai/v1/profiles/{profileId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

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

### Java: Create a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

Uses Unirest to POST the payload to the setup-session endpoint. Requires an API key in the X-API-Key header.

```java
HttpResponse<String> response = Unirest.post("https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://www.tinyfish.ai\",\n  \"timeout_seconds\": 300\n}")
  .asString();
```

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

### Create a profile setup session

Source: https://docs.tinyfish.ai/llms.txt

Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session expires or is cancelled.

```APIDOC
## POST /browser-context-profiles/setup-session

### Description
Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session expires or is cancelled.

### Method
POST

### Endpoint
/browser-context-profiles/setup-session

### Request Body
- **profile_id** (string) - Required - The ID of the browser context profile to set up.

### Request Example
{
  "profile_id": "string"
}

### Response
#### Success Response (200)
- **session_id** (string) - The session identifier.
- **cdp_url** (string) - The CDP connection URL.
- **base_url** (string) - The base URL for the setup browser.
- **timeout_seconds** (integer) - The session timeout in seconds.
- **expires_at** (string) - The expiration timestamp.

#### Response Example
{
  "session_id": "string",
  "cdp_url": "string",
  "base_url": "string",
  "timeout_seconds": 0,
  "expires_at": "string"
}
```

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

### Good goal example (specific and actionable)

Source: https://docs.tinyfish.ai/llms-full.txt

Use a specific, actionable goal to get better extraction results. This example extracts product name, price, and stock status from the product details section.

```typescript
goal: "Extract product name, price, and stock status from the product details section"
```

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

### JavaScript: Create a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

Uses fetch to POST the payload to the setup-session endpoint. Requires an API key in the X-API-Key header.

```javascript
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({url: 'https://www.tinyfish.ai', timeout_seconds: 300})
};

fetch('https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

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

### Java Unirest example for step HTML snapshot

Source: https://docs.tinyfish.ai/api-reference/runs/get-step-html-snapshot

Uses Unirest to GET the HTML snapshot as a string.

```java
HttpResponse<String> response = Unirest.get("https://agent.tinyfish.ai/v1/runs/{id}/steps/{stepId}/html")
  .header("X-API-Key", "<api-key>")
  .asString();

```

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

### Full example with both applied

Source: https://docs.tinyfish.ai/anti-bot-guide

Complete example combining stealth mode and proxy with streaming events. Handles completion and error statuses.

```python
from tinyfish import TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode, CompleteEvent, RunStatus

client = TinyFish()

with client.agent.stream(
    goal="Extract the product name and price",
    url="https://protected-site.com/products",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
    on_streaming_url=lambda e: print(f"Watch: {e.streaming_url}"),
    on_progress=lambda e: print(f"  > {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            if event.status == RunStatus.COMPLETED:
                print("Result:", event.result_json)
            else:
                print("Failed:", event.error.message if event.error else "unknown")

```

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

### Quick Decision Guide

Source: https://docs.tinyfish.ai/llms-full.txt

A guide to help choose between the /run, /run-async, and /run-sse endpoints based on task requirements.

```APIDOC
## Quick Decision Guide

### Description
Use this guide to select the appropriate run endpoint based on your needs.

- **Need real-time progress updates?** → Use `/run-sse`
- **Task takes longer than 30 seconds?** → Use `/run-async` + polling
- **Submitting multiple tasks at once?** → Use `/run-async` (parallel submission)
- **Simple, quick task?** → Use `/run` (synchronous)
```

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

### Install Docs MCP for Windsurf

Source: https://docs.tinyfish.ai/ai-integration

Quick install command for Windsurf.

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

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

### Connect vault, list items, and start a run with credentials

Source: https://docs.tinyfish.ai/vault-setup

Shows the three-step quick start: connect a vault provider, list available credentials, and start an automation run using a specific credential item ID. The first command returns a connectionId and initial items; the second reads from cache and returns item IDs; the third uses the credential_item_ids to scope the run.

```bash
# 1. Connect your vault (one-time setup)
curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "1password", "token": "ops_your_token" }'
# → returns connectionId and initial items

# 2. List available credentials (reads from cache — fast)
curl -s https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY"
# → grab the itemId for the credential you need

# 3. Start a run with that credential
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.linkedin.com",
    "goal": "Log in and capture the latest 3 posts from the feed",
    "use_vault": true,
    "credential_item_ids": [
      "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Work:item-linkedin"
    ]
  }'
```

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

### List vault items with Ruby

Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

Ruby example using Net::HTTP to GET /v1/vault/items. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://agent.tinyfish.ai/v1/vault/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

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

### Python: Create a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

Uses the requests library to POST the payload to the setup-session endpoint. Requires an API key in the X-API-Key header.

```python
import requests

url = "https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session"

payload = {
    "url": "https://www.tinyfish.ai",
    "timeout_seconds": 300
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

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

### List vault items with Java Unirest

Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

Java example using Unirest to GET /v1/vault/items. Returns an HttpResponse<String>.

```java
HttpResponse<String> response = Unirest.get("https://agent.tinyfish.ai/v1/vault/items")
  .header("X-API-Key", "<api-key>")
  .asString();
```

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

### Ruby: Create a profile setup session

Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

Uses Net::HTTP to POST the payload to the setup-session endpoint. Requires an API key in the X-API-Key header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://www.tinyfish.ai\",\n  \"timeout_seconds\": 300\n}"

response = http.request(request)
puts response.read_body
```

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

### Environment setup - .env with TINYFISH_API_KEY

Source: https://docs.tinyfish.ai/ai-integration

Set your TinyFish API key in a .env file. Get the key at https://agent.tinyfish.ai/api-keys.

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

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

### Full vault setup and run with credentials

Source: https://docs.tinyfish.ai/cli/commands

Complete workflow: connect a provider, sync and list items, then run an agent with vault credentials. Requires a TINYFISH_VAULT_TOKEN and a provider (e.g., 1password).

```bash
# 1. Connect (one-time)
TINYFISH_VAULT_TOKEN=ops_... tinyfish vault connection add --provider 1password

# 2. List items (sync first if the list is empty)
tinyfish vault item sync
tinyfish vault item list --pretty

# 3. Run with credentials
tinyfish agent run "Log in and export the invoices" \
  --url https://example.com \
  --use-vault \
  --credential-item-id cred:conn-123:Personal:item-abc123

```

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

### Create a monitor with tinyfish monitor create

Source: https://docs.tinyfish.ai/cli/commands

Creates a recurring monitor and runs its baseline immediately. Pass exactly one of `--query` (search monitor) or `--url` (fetch monitor). Each completed run, including the baseline, is billed to your wallet.

```bash
tinyfish monitor create --query "tinyfish funding news" --schedule "0 */6 * * *"
tinyfish monitor create --url https://example.com/pricing --schedule "0 9 * * *" --format markdown

```

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

### Successful response for Get research run by ID

Source: https://docs.tinyfish.ai/api-reference/get-research-run-by-id

Example response body for a successful GET request to /v1/research-run/{research_run_id}. Shows the full research run object including status, query, quick_result, deep_result, research_plan, evidence, and timestamps.

```json
{
  "research_run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "query": "What are the latest AI safety papers?",
  "quick_result": {
    "answer": "<string>",
    "citations": [
      "<string>"
    ],
    "actions": [
      {
        "id": "<string>",
        "label": "<string>",
        "status": "running",
        "streamingUrl": "<string>",
        "kind": "plan",
        "iteration": 1,
        "url": "<string>",
        "query": "<string>",
        "details": [
          "<string>"
        ]
      }
    ],
    "stats": {
      "iterations": 123,
      "sources_searched": 123,
      "sources_fetched": 123,
      "agent_runs": 123,
      "claims_extracted": 123,
      "termination_reason": "planner_done",
      "subquestions_covered": 123,
      "subquestions_total": 123
    }
  },
  "quick_result_summary": "<string>",
  "deep_result": {
    "result": "<string>",
    "citations": [
      "<string>"
    ],
    "freshness_report": {
      "sources_with_dates": 1,
      "sources_without_dates": 1,
      "sources_in_requested_window": 1,
      "filter_applied": {
        "domain_type": "news",
        "after_date": "2024-01-01",
        "before_date": "2024-12-31",
        "recency_minutes": 60
      },
      "latest_published_date": "<string>",
      "fetched_at_latest": "<string>"
    },
    "termination_reason": "planner_done"
  },
  "run_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "completed_at": "2026-01-01T12:05:00Z",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"url\" is required and must be a string",
    "details": "<unknown>"
  },
  "research_plan": {
    "summary": "<string>",
    "subquestions": [
      {
        "id": "<string>",
        "question": "<string>",
        "priority": "high"
      }
    ],
    "search_queries": [
      "<string>"
    ],
    "done": true,
    "review": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "pending",
      "expiresAt": 1,
      "feedback": "<string>",
      "resolvedAt": 1
    }
  },
  "evidence": [
    {
      "url": "<string>",
      "title": "<string>",
      "subquestions_covered": [
        "<string>"
      ],
      "claims": [
        {
          "claim": "<string>",
          "snippet": "<string>",
          "subquestion_id": "<string>",
          "confidence": "high",
          "claim_type": "fact"
        }
      ],
      "source_quality": "primary",
      "language": "<string>",
      "published_date": "<string>",
      "fetched_at": "<string>",
      "live_fetch": true,
      "access_method": "fetch",
      "discovered_by_queries": [
        "<string>"
      ],
      "search_filters": {
        "after_date": "<string>",
        "before_date": "<string>",
        "recency_minutes": 123
      }
    }
  ],
  "iterations": 3
}
```

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

### Full example in Python

Source: https://docs.tinyfish.ai/live-preview

Starts an automation, listens for the STREAMING_URL event in the SSE stream, and prints the streaming URL to embed in an iframe. Uses the tinyfish package.

```python
from tinyfish import TinyFish, StreamingUrlEvent

client = TinyFish()

with client.agent.stream(
    url="https://example.com/products",
    goal="Extract all product names and prices",
) as stream:
    for event in stream:
        if isinstance(event, StreamingUrlEvent):
            # Use this URL in an iframe to show the live browser
            print("Embed this:", event.streaming_url)
            break
```

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

### List vault items with PHP cURL

Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

PHP example using cURL to GET /v1/vault/items. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agent.tinyfish.ai/v1/vault/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

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

### List vault items with JavaScript fetch

Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

JavaScript example using fetch to GET /v1/vault/items. Logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://agent.tinyfish.ai/v1/vault/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```
Tokens:
Raw