Metadata-Version: 2.4
Name: metalift-sdk
Version: 1.0.1
Summary: Official Python SDK for the Metalift web context API
Author-email: Metalift <support@metalift.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://metalift.ai
Project-URL: Documentation, https://metalift.ai/docs
Project-URL: Repository, https://github.com/Endacoder/scraper-mcp
Project-URL: Issues, https://github.com/Endacoder/scraper-mcp/issues
Project-URL: Changelog, https://github.com/Endacoder/scraper-mcp/releases
Keywords: metalift,scraping,web-scraping,crawl,llm,agents,markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# metalift-sdk

Official Python SDK for [Metalift](https://app.metalift.ai) — turn any URL into agent-ready markdown, HTML, or structured data.

## Install

```bash
pip install metalift-sdk
```

Requires Python 3.10+.

## Quick start

```python
from metalift_sdk import Metalift

client = Metalift(api_key="YOUR_API_KEY")

result = client.scrape(
    "https://example.com",
    formats=["markdown"],
)
print(result["data"]["markdown"])
```

Get an API key from the [Metalift dashboard](https://app.metalift.ai/dashboard/keys). New accounts receive **1,000 free credits/month**.

## Configuration

```python
from metalift_sdk import Metalift

client = Metalift(
    api_url="https://api.metalift.ai",  # default
    api_key="YOUR_API_KEY",
    timeout=60.0,
)
```

Environment variables are also supported:

| Variable | Description |
|----------|-------------|
| `METALIFT_API_URL` | API base URL (default: `https://api.metalift.ai`) |
| `METALIFT_API_KEY` | Bearer token for authenticated requests |

## API

### Scrape

```python
client.scrape(
    "https://example.com",
    formats=["markdown"],
    render="auto",
    only_main_content=True,
    strategy="default",
)
```

### Batch scrape

```python
client.batch(
    ["https://example.com", "https://example.org"],
    async_=True,
    scrape_options={"formats": ["markdown"]},
)
```

### Crawl and map

```python
crawl_job = client.crawl("https://example.com", limit=50)
map_result = client.map("https://example.com", limit=100)
```

### Async jobs

```python
job = client.crawl("https://example.com", limit=20)
completed = client.wait_for_job(job["job_id"])
print(completed["status"], completed.get("data"))
```

### Strategies and protected sites

```python
strategies = client.list_strategies()
protection = client.list_protection_types()

client.scrape(
    "https://www.walmart.com/ip/EXAMPLE",
    strategy="retail",
    formats=["markdown"],
)

client.fetch_session(url="https://www.walmart.com/", domain="www.walmart.com")
```

### Session cookies

```python
client.seed_session(
    domain="example.com",
    cookies=[{"name": "session", "value": "...", "domain": "example.com", "path": "/"}],
)
```

## Errors

API failures raise `MetaliftError`:

```python
from metalift_sdk import Metalift, MetaliftError

try:
    client.scrape("https://example.com")
except MetaliftError as exc:
    print(exc.status_code, exc.detail)
```

## Links

- [Documentation](https://app.metalift.ai/docs)
- [API reference](https://app.metalift.ai/openapi/metalift.v1.yaml)
- [Support](mailto:support@metalift.ai)

## License & distribution

`metalift-sdk` is **proprietary software** licensed under the terms in [LICENSE](./LICENSE). Use, copying, modification, and redistribution are not permitted except as expressly authorized by Metalift.

The package is published on the public [Python Package Index (PyPI)](https://pypi.org/project/metalift-sdk/) so customers can install it with `pip install metalift-sdk`. Publishing on PyPI does **not** make the software open source: the wheel and source archive are publicly downloadable, but legal use remains governed by the proprietary license.

Do not commit API keys or other credentials into your application code. Pass them at runtime via the `api_key` argument or the `METALIFT_API_KEY` environment variable.
