capturedit 0.2.0

Official Python SDK for the CapturedIt Context Hub API

capturedit

Official Python SDK for the CapturedIt Context Hub API.

Install

pip install capturedit

Quick start

from capturedit import CapturedIt

client = CapturedIt(api_key="your_api_key")

# Search your library
results = client.search("machine learning")
for item in results.items:
    print(item.title)

# Get context for an AI prompt
context = client.get_context(q="project roadmap", format="text")

# Save a new item
result = client.create_item(
    "link",
    title="Interesting article",
    source_url="https://example.com/article",
)
print(f"Created item: {result.id}")

# Ask about a specific item
response = client.ask_about_item(result.id, question="Summarize this")
print(response.message)

Async usage

from capturedit import AsyncCapturedIt

async with AsyncCapturedIt(api_key="your_api_key") as client:
    results = await client.search("machine learning")
    for item in results.items:
        print(item.title)

Configuration

client = CapturedIt(
    api_key="your_api_key",
    base_url="https://api.capturedit.app",  # optional
    timeout=30.0,                            # optional, seconds
)

Methods

Method	Description
get_capabilities()	Returns plan tier and feature flags
search(query, *, limit, offset)	Full-text search over your items
get_context(*, limit, offset, q, format, include_conversations, max_chars)	Recent or query-relevant items for AI context
create_item(type, *, title, content_text, source_url, is_private)	Create a new item
capture_file(filename, mime_type, content_base64, *, ...)	Upload a file (base64)
get_item(item_id, *, include)	Get a single item with enrichments
delete_item(item_id)	Delete an item
transcribe(audio_base64, *, mime_type)	Speech-to-text (max 20MB decoded audio)
ask(question)	Ask a question across your library (uses your plan's ask quota)
ask_about_item(item_id, *, question, preset)	Ask about a specific item
list_conversations(item_id, *, limit, offset)	Paginated conversation history
delete_conversations(item_id)	Clear conversation history for an item

Webhook verification

from capturedit import verify_webhook_signature

is_valid = verify_webhook_signature(
    payload=request.body,
    header=request.headers["X-CapturedIt-Signature"],
    secret="your_webhook_secret",
)

Error handling

from capturedit import RateLimitError, AuthenticationError

try:
    results = client.search("query")
except RateLimitError as e:
    print(f"Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")

Requirements

• Python 3.10+
• CapturedIt API key (create at Dashboard → Security)
• All plans can use the API from the app surfaces; a Vault plan unlocks full integrator access (api_write) and the context endpoint. ask is available on all plans within your monthly quota.

Publishing (maintainers)

PyPI project name: capturedit.

1. First release (registers the project): from packages/sdk-python after tests:

   pip install build twine
   python -m build
   twine upload dist/*
   

   Use a PyPI API token with scope for this project.

2. Ongoing CI: In PyPI → Publishing → Add a trusted publisher → GitHub, point to this repository and workflow .github/workflows/publish-sdk-pypi.yml. Then use Actions → Publish capturedit to PyPI or push tag sdk-python/v0.1.0 (match pyproject.toml version).

3. Version bumps: Edit version in pyproject.toml before each release.