Navigate page

Navigate to a URL, go back/forward, or refresh the page

Navigate to URL

POST /tabs/:tabId/navigate

Navigates the tab to a new URL or search query using macros.

Path parameters

tabId · string · required

The unique identifier of the tab

Body parameters

userId · string · required

User identifier for session isolation

url · string

Direct URL to navigate to (e.g., https://example.com). Either url or macro is required.

macro · string

Search macro name (e.g., @google_search, @youtube_search). Either url or macro is required.

query · string

Search query to use with macro (required if macro is provided)

sessionKey · string

Session key for grouping tabs (legacy parameter: listItemId also accepted)

Response

ok · boolean

Always true on success

tabId · string

The tab identifier

url · string

The final URL after navigation (may differ from requested URL due to redirects)

refsAvailable · boolean

Whether element references were successfully built for the loaded page

Search macros

Macros expand to search URLs for popular websites:

Macro	Expands to
@google_search	https://www.google.com/search?q={query}
@youtube_search	https://www.youtube.com/results?search_query={query}
@amazon_search	https://www.amazon.com/s?k={query}
@reddit_search	https://www.reddit.com/search.json?q={query}&limit=25
@wikipedia_search	https://en.wikipedia.org/wiki/Special:Search?search={query}
@twitter_search	https://twitter.com/search?q={query}
@yelp_search	https://www.yelp.com/search?find_desc={query}
@linkedin_search	https://www.linkedin.com/search/results/all/?keywords={query}
@spotify_search	https://open.spotify.com/search/{query}
@netflix_search	https://www.netflix.com/search?q={query}
@instagram_search	https://www.instagram.com/explore/tags/{query}
@tiktok_search	https://www.tiktok.com/search?q={query}
@twitch_search	https://www.twitch.tv/search?term={query}
@reddit_subreddit	https://www.reddit.com/r/{query}.json?limit=25

Auto-tab creation

If the specified tabId doesn’t exist, a new tab is automatically created (up to session limits). This allows simplified workflows without separate /tabs POST.

Navigation behavior

• Waits for domcontentloaded event (default timeout: 30s)
• Attempts to wait for network idle (5s timeout, continues if missed)
• Waits for framework hydration (React/Next.js/Vue detection)
• Auto-dismisses common consent/privacy dialogs
• Builds element references after page load
• Resets cached snapshots and refs

---

Go back

POST /tabs/:tabId/back

Navigates to the previous page in the tab’s history.

Path parameters

tabId · string · required

The unique identifier of the tab

Body parameters

userId · string · required

User identifier for session isolation

Response

ok · boolean

Always true on success

url · string

The URL after navigating back

---

Go forward

POST /tabs/:tabId/forward

Navigates to the next page in the tab’s history.

Path parameters

tabId · string · required

The unique identifier of the tab

Body parameters

userId · string · required

User identifier for session isolation

Response

ok · boolean

Always true on success

url · string

The URL after navigating forward

---

Refresh page

POST /tabs/:tabId/refresh

Reloads the current page.

Path parameters

tabId · string · required

The unique identifier of the tab

Body parameters

userId · string · required

User identifier for session isolation

Response

ok · boolean

Always true on success

url · string

The current URL (unchanged)

---

Error codes

• 400 - Missing required parameter or invalid URL scheme (only http/https allowed)
• 404 - Tab not found
• 429 - Maximum tabs per session reached (when auto-creating tab)
• 500 - Navigation failed (timeout, network error)

Examples

Navigate to direct URL

curl -X POST http://localhost:9377/tabs/abc123/navigate \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "url": "https://example.com"
  }'

{
  "ok": true,
  "tabId": "abc123",
  "url": "https://example.com/",
  "refsAvailable": true
}

Search using macro

curl -X POST http://localhost:9377/tabs/abc123/navigate \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "macro": "@google_search",
    "query": "headless browser automation"
  }'

{
  "ok": true,
  "tabId": "abc123",
  "url": "https://www.google.com/search?q=headless+browser+automation",
  "refsAvailable": true
}

Go back in history

curl -X POST http://localhost:9377/tabs/abc123/back \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1"
  }'

{
  "ok": true,
  "url": "https://example.com"
}

Go forward in history

curl -X POST http://localhost:9377/tabs/abc123/forward \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1"
  }'

{
  "ok": true,
  "url": "https://example.com/page2"
}

Refresh page

curl -X POST http://localhost:9377/tabs/abc123/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1"
  }'

{
  "ok": true,
  "url": "https://example.com"
}

Best practices

1. Use macros for search: Simpler and more maintainable than manually constructing URLs
2. Check refsAvailable: If false, the page may still be loading - wait and retry /snapshot
3. Handle redirects: The returned url may differ from the requested URL
4. Allow timeout buffer: Complex sites may take 10-20s to fully load
5. Call /snapshot after navigation: Element refs are rebuilt but not returned in navigate response