# Agent

## Automate

**post** `/automate`

Execute AI-powered browser automation tasks using natural language with optional geotargeting. This endpoint **always streams** responses using Server-Sent Events (SSE).

**Streaming Response:**

- All responses are streamed using Server-Sent Events (`text/event-stream`)
- Real-time progress updates and results as they're generated

**Geotargeting:**

- Optionally specify a country code for geotargeted browsing

**Use Cases:**

- Web scraping and data extraction
- Form filling and interaction
- Navigation and information gathering
- Multi-step web workflows
- Content analysis from web pages

### Body Parameters

- `task: string`

  The task description in natural language

- `data: optional unknown`

  JSON data to provide context for form filling or complex tasks

- `geo_target: optional object { country }`

  Optional geotargeting parameters for proxy requests

  - `country: optional string`

    Country code using ISO 3166-1 alpha-2 standard (2 letters, e.g., "US", "GB", "JP").
    See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

- `guardrails: optional string`

  Safety constraints for execution

- `maxIterations: optional number`

  Maximum task iterations

- `maxValidationAttempts: optional number`

  Maximum validation attempts

- `url: optional string`

  Starting URL for the task

### Returns

- `AutomateEvent = object { data, event }`

  - `data: optional unknown`

    Event payload data

  - `event: optional string`

    The event type (e.g., start, agent:processing, complete)

### Example

```http
curl https://api.tabstack.ai/v1/automate \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TABSTACK_API_KEY" \
    -d "{
          \"task\": \"Find the top 3 trending repositories and extract their names, descriptions, and star counts\",
          \"guardrails\": \"browse and extract only, don't interact with repositories\",
          \"maxIterations\": 50,
          \"maxValidationAttempts\": 3,
          \"url\": \"https://github.com/trending\"
        }"
```

## Research

**post** `/research`

Execute AI-powered research queries that search the web, analyze sources, and synthesize comprehensive answers. This endpoint **always streams** responses using Server-Sent Events (SSE).

**Streaming Response:**

- All responses are streamed using Server-Sent Events (`text/event-stream`)
- Real-time progress updates as research progresses through phases

**Research Modes:**

- `fast` - Quick answers with minimal web searches
- `balanced` - Standard research with multiple iterations (default)

**Use Cases:**

- Answering complex questions with cited sources
- Synthesizing information from multiple web sources
- Research reports on specific topics
- Fact-checking and verification tasks

### Body Parameters

- `query: string`

  The research query or question to answer

- `fetch_timeout: optional number`

  Timeout in seconds for fetching web pages

- `mode: optional "fast" or "balanced"`

  Research mode: fast (quick answers), balanced (standard research, default)

  - `"fast"`

  - `"balanced"`

- `nocache: optional boolean`

  Skip cache and force fresh research

### Returns

- `ResearchEvent = object { data, event }`

  - `data: optional unknown`

    Event payload data

  - `event: optional "phase" or "progress" or "complete" or "error"`

    The event type: phase, progress, complete, or error

    - `"phase"`

    - `"progress"`

    - `"complete"`

    - `"error"`

### Example

```http
curl https://api.tabstack.ai/v1/research \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TABSTACK_API_KEY" \
    -d '{
          "query": "What are the latest developments in quantum computing?",
          "fetch_timeout": 30,
          "mode": "balanced"
        }'
```

## Domain Types

### Automate Event

- `AutomateEvent = object { data, event }`

  - `data: optional unknown`

    Event payload data

  - `event: optional string`

    The event type (e.g., start, agent:processing, complete)

### Research Event

- `ResearchEvent = object { data, event }`

  - `data: optional unknown`

    Event payload data

  - `event: optional "phase" or "progress" or "complete" or "error"`

    The event type: phase, progress, complete, or error

    - `"phase"`

    - `"progress"`

    - `"complete"`

    - `"error"`