Python SDK Quickstart

Get up and running with the Tabstack Python SDK in minutes. This guide will walk you through installation, authentication, and your first API call.

Prerequisites

• Python >= 3.9
• Package manager: pip, uv, poetry, or pipenv
• Tabstack API key from console.tabstack.ai

Installation

Install the SDK using your preferred package manager:

uv

uv pip install tabstack

Or add to your project:

uv add tabstack

pip

pip install tabstack

poetry

poetry add tabstack

pipenv

pipenv install tabstack

The current SDK version is 2.0.0.

Get Your API Key

Before you can start using the SDK, you'll need to create an API key:

1. Visit the Tabstack Console
2. Sign in to your account (or create one if you haven't already)
3. Navigate to the API Keys section and click "Manage API Keys"
4. Click "Create New API Key"
5. Give your key a descriptive name (e.g., "Development", "Production")
6. Copy the generated API key and store it securely

Important: Your API key will only be shown once. Make sure to copy and store it in a secure location.

Set Up Environment Variable

For security and convenience, store your API key as an environment variable:

macOS/Linux:

# Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile)
export TABSTACK_API_KEY="your_api_key_here"

# Or set it temporarily for the current session
export TABSTACK_API_KEY="your_api_key_here"

# Reload your shell or run:
source ~/.bashrc  # or ~/.zshrc

Windows (Command Prompt):

# Set temporarily for current session
set TABSTACK_API_KEY=your_api_key_here

# Set permanently (requires restart)
setx TABSTACK_API_KEY "your_api_key_here"

Windows (PowerShell):

# Set temporarily for current session
$env:TABSTACK_API_KEY = "your_api_key_here"

# Set permanently for current user
[Environment]::SetEnvironmentVariable("TABSTACK_API_KEY", "your_api_key_here", "User")

Your First API Call

The Python SDK provides both synchronous and asynchronous clients. Use context managers for automatic resource cleanup.

Sync Example (Recommended for Simple Scripts)

import os
from tabstack import Tabstack

# Initialize the sync client with context manager
with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    try:
        # Extract markdown from a URL
        result = client.extract.markdown(url='https://example.com')
        print(result.content)
    except Exception as error:
        print(f'Error: {error}')

Async Example

If you need async support, use AsyncTabstack:

import asyncio
import os
from tabstack import AsyncTabstack

async def main():
    # Initialize the async client with async context manager
    async with AsyncTabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        try:
            # Extract markdown from a URL
            result = await client.extract.markdown(url='https://example.com')
            print(result.content)
        except Exception as error:
            print(f'Error: {error}')

# Run the async function
asyncio.run(main())

Response:

---
title: Example Domain
description: Example Domain
url: https://example.com
type: website
---

# Example Domain

This domain is for use in illustrative examples in documents. You may use this
domain in literature without prior coordination or asking for permission.

[More information...](https://www.iana.org/domains/example)

Core Features

The SDK provides three main operators for working with web content:

Extract

Convert web pages to structured data:

• Markdown: Convert HTML to clean Markdown format
• JSON: Extract structured data matching your schema

Generate

Transform web content using AI:

• Summarize and analyze content
• Categorize and tag data
• Perform sentiment analysis
• Extract key insights with custom instructions

Learn more about Generate features →

Automate

Execute browser automation tasks with natural language:

• Web scraping with real-time updates
• Form filling and submission
• Multi-step workflows
• Streaming progress events

Learn more about Automate features →

Quick Example: Extract Structured Data

Here's a more advanced example that extracts structured data from a web page:

import os
from tabstack import Tabstack

with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    # Define the data structure you want
    schema = {
        "type": "object",
        "properties": {
            "stories": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "points": {"type": "number"},
                        "author": {"type": "string"}
                    },
                    "required": ["title", "points", "author"]
                }
            }
        },
        "required": ["stories"]
    }

    try:
        # Extract data matching the schema
        result = client.extract.json(
            url='https://news.ycombinator.com',
            json_schema=schema
        )

        print(f"Found {len(result['stories'])} stories:")
        for story in result['stories'][:3]:  # Show first 3
            print(f"- {story['title']} ({story['points']} points) by {story['author']}")

    except Exception as error:
        print(f'Error: {error}')

Client Configuration

The SDK provides several configuration options:

import httpx
from tabstack import Tabstack

client = Tabstack(
    api_key="your-api-key",                    # Required (or TABSTACK_API_KEY env var)
    base_url="https://api.tabstack.ai/v1",     # Optional, defaults to this
    timeout=60.0,                              # Request timeout in seconds (default: 60)
    max_retries=2,                             # Max retry attempts (default: 2)
    default_headers={"X-Custom": "header"},    # Optional custom headers
)

Environment Variables

Variable	Description
TABSTACK_API_KEY	API key for authentication
TABSTACK_BASE_URL	Override the default API base URL
TABSTACK_LOG	Set to info or debug to enable logging

Timeout Configuration

For more granular control over timeouts:

import httpx
from tabstack import Tabstack

client = Tabstack(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0)
)

Concurrent Requests (Async)

Use asyncio.gather() for concurrent requests with the async client:

import asyncio
import os
from tabstack import AsyncTabstack

async def fetch_multiple():
    async with AsyncTabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        # Run multiple requests concurrently
        results = await asyncio.gather(
            client.extract.markdown(url='https://example.com/1'),
            client.extract.markdown(url='https://example.com/2'),
            client.extract.markdown(url='https://example.com/3'),
            return_exceptions=True  # Don't fail all if one fails
        )

        for i, result in enumerate(results):
            if isinstance(result, Exception):
                print(f"Request {i} failed: {result}")
            else:
                print(f"Request {i}: {len(result.content)} characters")

asyncio.run(fetch_multiple())

Per-Request Options

Override client defaults for individual requests:

from tabstack import Tabstack

with Tabstack() as client:
    # Override timeout and retries for this specific request
    result = client.with_options(
        timeout=120.0,
        max_retries=5
    ).extract.json(
        url='https://example.com',
        json_schema={"type": "object", "properties": {"title": {"type": "string"}}}
    )

Best Practices

Using Context Managers

Always use context managers to ensure proper cleanup:

# Sync - Good: Automatic cleanup
with Tabstack(api_key=api_key) as client:
    result = client.extract.markdown(url=url)

# Sync - Not recommended: Manual cleanup required
client = Tabstack(api_key=api_key)
try:
    result = client.extract.markdown(url=url)
finally:
    client.close()

# Async - Good: Automatic cleanup
async with AsyncTabstack(api_key=api_key) as client:
    result = await client.extract.markdown(url=url)

Error Handling

Always wrap API calls in try-except blocks:

from tabstack import Tabstack, TabstackError

with Tabstack(api_key=api_key) as client:
    try:
        result = client.extract.markdown(url='https://example.com')
        return result
    except TabstackError as error:
        print(f"API error: {error}")
        return None

Next Steps

Now that you're up and running:

1. Generate Features: Discover AI-powered content transformation and analysis
2. Automate Features: Execute complex browser automation tasks with streaming updates
3. Error Handling: Build robust applications with proper error handling

Need Help?

• API Reference: REST API Documentation
• PyPI: Python Package Index
• GitHub: Python SDK Repository
• Documentation: docs.tabstack.ai
• Support: [email protected]