browser-automation-notte

# Notte - Browser Automation API

## Setup

Read your credentials from ~/.gooseworks/credentials.json:
```bash
export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")
```

If ~/.gooseworks/credentials.json does not exist, tell the user to run: `npx gooseworks login`

All endpoints use Bearer auth: `-H "Authorization: Bearer $GOOSEWORKS_API_KEY"`


Control browser sessions, scrape web pages, and run autonomous AI agents.

## Capabilities

- **Take Screenshot**: Take a screenshot of the current page
- **Get Session**: Get session status and details (free)
- **Stop Session**: Stop and clean up a browser session (free)
- **Get Session Cookies**: Get all cookies from the browser session (free)
- **Get Network Logs**: Get network request/response logs from the session (free)
- **Get Agent Status**: Get agent execution status and results (free)
- **Observe Page**: Observe the current page state and get available actions
- **Stop Agent**: Stop a running agent (free)
- **Scrape Webpage**: Scrape content from a URL without managing sessions
- **Execute Page Action**: Execute an action on the page (click, type, navigate, etc
- **Set Session Cookies**: Set cookies in the browser session
- **Start Session**: Start a new browser session
- **Scrape from HTML**: Extract structured content from raw HTML without using a browser
- **Start Agent**: Start an AI agent to autonomously complete a browser task
- **Scrape Page**: Scrape content from the current page in the session

## Usage

### Take Screenshot
Take a screenshot of the current page.

Parameters:
- full_page (boolean) - Capture full page
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/page/screenshot","body":{}}'
```

### Get Session (free)
Get session status and details.

Parameters:
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}"}'
```

### Stop Session (free)
Stop and clean up a browser session.

Parameters:
- session_id* (string) - Session ID

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/stop"}'
```

### Get Session Cookies (free)
Get all cookies from the browser session.

Parameters:
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/cookies"}'
```

### Get Network Logs (free)
Get network request/response logs from the session.

Parameters:
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/network/logs","query":{"session_id":"example"}}'
```

### Get Agent Status (free)
Get agent execution status and results.

Parameters:
- agent_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/agents/{agent_id}"}'
```

### Observe Page
Observe the current page state and get available actions.

Parameters:
- max_nb_actions (number) - Maximum actions to return (default: 100)
- min_nb_actions (number) - Minimum actions to return
- instruction (string) - Optional instruction to filter actions
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/page/observe","body":{"instruction":"Find the search box"}}'
```

### Stop Agent (free)
Stop a running agent.

Parameters:
- session_id* (string) - Session ID the agent is running on

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/agents/{agent_id}/stop"}'
```

### Scrape Webpage
Scrape content from a URL without managing sessions.

Parameters:
- url* (string) - URL to scrape
- schema (object) - Structured extraction schema

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/scrape","body":{"url":"https://example.com"}}'
```

### Execute Page Action
Execute an action on the page (click, type, navigate, etc.).

Parameters:
- type* (string) - Action type: goto, click, type, scroll, select, hover, wait, screenshot
- url (string) - URL for goto action
- ref (string) - Element reference for click/type/select actions
- text (string) - Text for type action
- value (string) - Value for select action
- direction (string) - Scroll direction: up/down
- amount (number) - Scroll amount in pixels
- timeout (number) - Wait timeout in ms
- session_id* (string)

```bash
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"notte","path":"/sessions/{session_id}/page/execute","body":{"instruction":"Click the search button"}}'
```

### Set Session Cookies
Set cookies in the brows