Cookies API - PinchTab

Overview

The Cookies API allows you to:

Get cookies for a URL or tab
Set cookies programmatically
Manage cookie attributes (domain, path, expiry)
Filter cookies by name

Get Cookies

Retrieve cookies for a tab or URL.

GET /tabs/{id}/cookies

curl "http://localhost:9867/tabs/tab_abc123/cookies" | jq .

Query Parameters

url

string

URL to get cookies for (defaults to tab’s current URL)

name

string

Filter to specific cookie name

Response (200 OK)

{
  "url": "https://example.com",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123def456",
      "domain": "example.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "expires": 1735689600
    },
    {
      "name": "user_prefs",
      "value": "dark_mode=true",
      "domain": ".example.com",
      "path": "/",
      "secure": false,
      "httpOnly": false,
      "sameSite": "None"
    }
  ],
  "count": 2
}

Response Fields

url

string

required

URL for which cookies were retrieved

array

required

Array of cookie objects

count

integer

required

Number of cookies

name

string

required

Cookie name

value

string

required

Cookie value

domain

string

required

Cookie domain

path

string

required

Cookie path

secure

boolean

required

HTTPS only flag

httpOnly

boolean

required

JavaScript access blocked flag

sameSite

string

required

SameSite attribute: Strict, Lax, or None

expires

number

Expiration timestamp (Unix epoch)

Set Cookies

Set one or more cookies for a tab.

POST /tabs/{id}/cookies

curl -X POST http://localhost:9867/tabs/tab_abc123/cookies \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax"
      }
    ]
  }'

Request Body

url

string

required

URL to set cookies for

array

required

Array of cookie objects to set

name

string

required

Cookie name

value

string

required

Cookie value

domain

string

Cookie domain (defaults from URL)

path

string

Cookie path (default: /)

secure

boolean

default:"false"

HTTPS only

httpOnly

boolean

default:"false"

Block JavaScript access

sameSite

string

SameSite attribute: Strict, Lax, or None

expires

number

Expiration timestamp (Unix epoch)

Response (200 OK)

{
  "set": 2,
  "failed": 0,
  "total": 2
}

Complete Example

import requests
import time

BASE = "http://localhost:9867"

# Start instance
inst = requests.post(f"{BASE}/instances/start",
    json={"mode": "headed"}).json()

# Open tab
tab = requests.post(f"{BASE}/instances/{inst['id']}/tabs/open",
    json={"url": "https://example.com"}).json()

tab_id = tab["tabId"]
time.sleep(2)

# Get existing cookies
resp = requests.get(f"{BASE}/tabs/{tab_id}/cookies")
cookies = resp.json()
print(f"Existing cookies: {cookies['count']}\n")

for cookie in cookies["cookies"]:
    print(f"{cookie['name']}: {cookie['value']}")

# Set new cookies
resp = requests.post(f"{BASE}/tabs/{tab_id}/cookies", json={
    "url": "https://example.com",
    "cookies": [
        {
            "name": "custom_session",
            "value": "my_session_token",
            "secure": True,
            "httpOnly": True,
            "sameSite": "Lax"
        },
        {
            "name": "user_preference",
            "value": "dark_theme",
            "path": "/"
        }
    ]
})

result = resp.json()
print(f"\nSet {result['set']} new cookies")

# Verify cookies were set
resp = requests.get(f"{BASE}/tabs/{tab_id}/cookies")
cookies = resp.json()
print(f"\nTotal cookies now: {cookies['count']}")

# Cleanup
requests.post(f"{BASE}/instances/{inst['id']}/stop")

def get_cookie_by_name(tab_id, name, url=""):
    """Get a specific cookie by name"""
    resp = requests.get(
        f"http://localhost:9867/tabs/{tab_id}/cookies",
        params={"name": name, "url": url} if url else {"name": name}
    )
    cookies = resp.json()["cookies"]
    return cookies[0] if cookies else None

def set_session_cookie(tab_id, url, session_id):
    """Set a session cookie"""
    requests.post(
        f"http://localhost:9867/tabs/{tab_id}/cookies",
        json={
            "url": url,
            "cookies": [{
                "name": "session_id",
                "value": session_id,
                "secure": True,
                "httpOnly": True,
                "sameSite": "Lax"
            }]
        }
    )

def export_cookies(tab_id, url=""):
    """Export all cookies to dict"""
    resp = requests.get(
        f"http://localhost:9867/tabs/{tab_id}/cookies",
        params={"url": url} if url else {}
    )
    return {c["name"]: c["value"] for c in resp.json()["cookies"]}

def import_cookies(tab_id, url, cookies_dict):
    """Import cookies from dict"""
    cookies = [
        {"name": name, "value": value}
        for name, value in cookies_dict.items()
    ]
    requests.post(
        f"http://localhost:9867/tabs/{tab_id}/cookies",
        json={"url": url, "cookies": cookies}
    )

# Usage
session = get_cookie_by_name(tab_id, "session_id")
if session:
    print(f"Session: {session['value']}")

set_session_cookie(tab_id, "https://example.com", "new_session_token")

cookies = export_cookies(tab_id)
print(f"Exported {len(cookies)} cookies")

SameSite Attribute

Value	Description	Use Case
Strict	Only sent to same-site requests	Maximum security
Lax	Sent on top-level navigation	Balanced security
None	Sent on all requests	Cross-site scenarios (requires `secure: true`)

Example:

# Strict (most secure)
{"name": "token", "value": "abc", "sameSite": "Strict", "secure": True}

# Lax (balanced)
{"name": "session", "value": "xyz", "sameSite": "Lax", "secure": True}

# None (cross-site, must be secure)
{"name": "tracking", "value": "123", "sameSite": "None", "secure": True}

Error Handling

Tab Not Found (404)

curl "http://localhost:9867/tabs/nonexistent/cookies"

Response:

{
  "error": "tab not found",
  "statusCode": 404
}

curl -X POST http://localhost:9867/tabs/tab_abc123/cookies \
  -d '{"url":"https://example.com","cookies":[]}'

Response:

{
  "error": "cookies array is empty",
  "statusCode": 400
}

Best Practices

Always Specify URL

# ✅ Good: Explicit URL
requests.post(f"{BASE}/tabs/{tab_id}/cookies", json={
    "url": "https://example.com",
    "cookies": [...]
})

# ❌ Bad: Missing URL
requests.post(f"{BASE}/tabs/{tab_id}/cookies", json={
    "cookies": [...]
})

Use Secure Cookies

# For HTTPS sites, always use secure cookies
{
    "name": "session",
    "value": "token",
    "secure": True,  # ← Important!
    "httpOnly": True,
    "sameSite": "Lax"
}

Set Expiration for Persistence

import time

# Expire in 7 days
expire_time = int(time.time()) + (7 * 24 * 60 * 60)

{
    "name": "remember_me",
    "value": "yes",
    "expires": expire_time
}

Next Steps

Authentication

API authentication and security

Stealth Mode

Stealth and fingerprint management

Navigation

Navigate with cookies

Evaluation

Access cookies via JavaScript

Documentation Index

​Overview

​Get Cookies

​Query Parameters

​Response (200 OK)

​Response Fields

​Cookie Fields

​Set Cookies

​Request Body

​Cookie Object

​Response (200 OK)

​Complete Example

​Cookie Management Example

​SameSite Attribute

​Error Handling

​Tab Not Found (404)

​Invalid Cookie (400)

​Best Practices

​Always Specify URL

​Use Secure Cookies

​Set Expiration for Persistence

​Next Steps

Authentication

Stealth Mode

Navigation

Evaluation

Overview

Get Cookies

Query Parameters

Response (200 OK)

Response Fields

Cookie Fields

Set Cookies

Request Body

Cookie Object

Response (200 OK)

Complete Example

Cookie Management Example

SameSite Attribute

Error Handling

Tab Not Found (404)

Invalid Cookie (400)

Best Practices

Always Specify URL

Use Secure Cookies

Set Expiration for Persistence

Next Steps