Python SDK

The Python SDK wraps the ctxd REST API. Sync and async clients available.

Install

pip install ctxd

Quick example

from ctxd import Client

with Client(api_key="your-api-key") as client:
    result = client.search("text:deployment application:slack")

for item in result.results:
    print(item.id)
    print(item.title)
    print(item.url)
    print(item.text)

Authentication

The client looks for an API key in this order:

1. api_key parameter passed to Client()
2. CTXD_API_KEY environment variable
3. local CLI login from ctxd login

# Explicit key
client = Client(api_key="your-key")

# From env var or saved API key
client = Client()

Use ctxd login for interactive local authentication.

Search

# Simple search
result = client.search("text:deployment")

# With filters
result = client.search("text:deployment application:slack date:>2025-01-01")

# Boolean operators
result = client.search("text:(bug* OR issue) repo:team/backend")

client.search() returns a SearchResult:

class SearchResult:
    results: list[SearchItem]
    error: str | None
    dsl_parse_error: str | None

Each SearchItem includes:

class SearchItem:
    id: str
    title: str
    url: str
    text: str
    metadata: dict

Fetch a document

doc = client.fetch_document("document-uid")
print(doc.title)
print(doc.text)
print(doc.url)

Returns a DocumentResult:

class DocumentResult:
    id: str | None
    title: str
    url: str
    text: str
    metadata: dict
    error: str | None

Get profile

profile = client.get_profile()

# Markdown summary of connected integrations
print(profile.integration_access)

# See indexed file tree
print(profile.file_tree)

client.get_profile() returns a ProfileResult:

class ProfileResult:
    integration_access: str
    file_tree: str

Async client

from ctxd import AsyncClient

async with AsyncClient() as client:
    results = await client.search("text:deployment")
    doc = await client.fetch_document("doc-uid")
    profile = await client.get_profile()

Context manager

with Client() as client:
    results = client.search("text:deployment")

Custom base URL

client = Client(
    api_key="your-key",
    base_url="https://your-instance.example.com",
    timeout=60.0,
)