Metadata-Version: 2.4
Name: captapi
Version: 0.2.0
Summary: Official typed Python SDK for the Captapi social media API - 178 endpoints across 32 platforms (YouTube, TikTok, Instagram, Facebook, X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Twitch, Spotify, and more).
Project-URL: Homepage, https://captapi.com
Project-URL: Documentation, https://captapi.com/docs
Project-URL: Repository, https://github.com/CDCStream/captapi
Author-email: Captapi <support@captapi.com>
License: MIT
Keywords: api-client,captapi,instagram,reddit,scraping,sdk,social-media,tiktok,transcript,twitter,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# captapi

Official typed Python SDK for the [Captapi](https://captapi.com) social media API — 178 endpoints across 32 platforms (YouTube, TikTok, Instagram, Facebook, X/Twitter, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Twitch, Spotify, SoundCloud, GitHub, and more).

- Sync **and** async clients (`Captapi` / `AsyncCaptapi`), built on `httpx`
- Typed, documented method for every endpoint — great autocomplete for humans and AI coding agents
- Errors always raise `CaptapiError` with status code and detail — no silent failures
- One bounded retry on 502/503 (skipped when the API says the failure is persistent or already cached)

## Install

```bash
pip install captapi
```

## Quick start

```python
from captapi import Captapi

client = Captapi(api_key="YOUR_KEY")  # or set CAPTAPI_API_KEY

transcript = client.youtube.transcript(url="https://youtube.com/watch?v=dQw4w9WgXcQ")
print(transcript["data"])

profile = client.tiktok.channel_details(url="https://tiktok.com/@nba")
posts = client.reddit.subreddit_posts(url="https://reddit.com/r/programming", limit=25)
ads = client.google_ad_library.company_ads(advertiser="nike.com")
```

## Async

```python
from captapi import AsyncCaptapi

async with AsyncCaptapi() as client:
    result = await client.instagram.channel_details(url="https://instagram.com/nba")
```

## Error handling

Every failed request raises — nothing fails silently:

```python
from captapi import Captapi, CaptapiError

try:
    client.instagram.channel_details(url="https://instagram.com/whoever")
except CaptapiError as err:
    print(err.status_code, err.code, err.detail)
```

## Responses

All methods return the standard Captapi envelope as a `dict`:

```json
{ "success": true, "data": { ... } }
```

## Links

- [Documentation](https://captapi.com/docs)
- [Get an API key (100 free credits)](https://captapi.com/dashboard/api-keys)
- TypeScript SDK: [`npm install @captapi/sdk`](https://www.npmjs.com/package/@captapi/sdk)
- MCP server for AI agents: [`@captapi/mcp`](https://www.npmjs.com/package/@captapi/mcp)
- CLI: [`@captapi/cli`](https://www.npmjs.com/package/@captapi/cli)
