xr2-sdk 0.2.4

Official Python SDK for xR2 product API

xR2 SDK (Python)

Official Python client for xR2 APIs.

Installation

pip install xr2-sdk

Quickstart (Sync)

from xr2_sdk.client import xR2Client

client = xR2Client(api_key="YOUR_PRODUCT_API_KEY")

# Check API key validity
key_response = client.check_api_key()
if key_response.ok:
    print(f"API key valid for user: {key_response.data.user}")

# Get prompt
prompt_response = client.get_prompt(slug="welcome")

if prompt_response.ok:
    prompt = prompt_response.data
    print(f"slug: {prompt.slug}")
    print(f"version_number: {prompt.version_number}")
    print(f"system_prompt: {prompt.system_prompt}")
    print(f"user_prompt: {prompt.user_prompt}")
    print(f"variables: {prompt.variables}")
    print(f"trace_id: {prompt.trace_id}")

    # Track an event
    event_response = client.track_event(
        trace_id=prompt.trace_id,
        event_name="sign_up",
        user_id="user_123",
        metadata={},
    )

    if event_response.ok:
        print(f"Event tracked: {event_response.data.event_id}")

    # Track a purchase event with value
    purchase_response = client.track_event(
        trace_id=prompt.trace_id,
        event_name="purchase_completed",
        user_id="user_123",
        value=99.99,
        currency="USD",
        metadata={"order_id": "order_67890", "product_id": "prod_456"},
    )

Quickstart (Async)

import asyncio
from xr2_sdk.client import AsyncxR2Client

async def main():
    client = AsyncxR2Client(api_key="YOUR_PRODUCT_API_KEY")
    try:
        # Check API key validity
        key_response = await client.check_api_key()
        if key_response.ok:
            print(f"API key valid for user: {key_response.data.user}")

        # Get prompt
        prompt_response = await client.get_prompt(slug="welcome")

        if prompt_response.ok:
            prompt = prompt_response.data
            print(f"slug: {prompt.slug}")
            print(f"version_number: {prompt.version_number}")
            print(f"system_prompt: {prompt.system_prompt}")
            print(f"user_prompt: {prompt.user_prompt}")
            print(f"variables: {prompt.variables}")
            print(f"trace_id: {prompt.trace_id}")

            # Track an event
            event_response = await client.track_event(
                trace_id=prompt.trace_id,
                event_name="sign_up",
                user_id="user_123",
                metadata={},
            )

            if event_response.ok:
                print(f"Event tracked: {event_response.data.event_id}")

            # Track a purchase event with value
            purchase_response = await client.track_event(
                trace_id=prompt.trace_id,
                event_name="purchase_completed",
                user_id="user_123",
                value=99.99,
                currency="USD",
                metadata={"order_id": "order_67890", "product_id": "prod_456"},
            )
    finally:
        await client.aclose()

asyncio.run(main())

Endpoints

• GET /api/v1/check-api-key → validates API key and returns username
• POST /api/v1/get-prompt → returns prompt content and trace_id
• POST /api/v1/events → records an event associated with trace_id

Configuration

• api_key: Product API key (sent as Authorization: Bearer <key>)
• timeout: Request timeout (seconds)
• total_retries, backoff_factor: Retry policy (sync) / lightweight retry (async)

API Methods

check_api_key()

Validate your API key and get the associated username.

Parameters: None

Returns: Response[CheckAPIKeyResponse]

• response.data.ok: Always True if valid
• response.data.user: Username of the API key owner

get_prompt()

Parameters:

• slug (required): The prompt slug identifier
• version_number (optional): Specific version number to fetch
• status (optional): Version status filter - draft, testing, production, inactive, deprecated

Returns: Response[PromptContentResponse]

• Access data: response.data.trace_id, response.data.user_prompt, etc.
• Check success: if response.ok:

track_event()

Required Parameters:

• trace_id: Trace ID from get_prompt() response
• event_name: Event name as defined in dashboard (e.g., "sign_up", "purchase_completed")

Optional Parameters:

• user_id: User identifier for tracking
• session_id: Session identifier for analytics
• value: Numeric value (for revenue tracking, order amounts, etc.)
• currency: Currency code (e.g., "USD", "EUR")
• metadata: Dictionary of custom fields as defined in event definition schema

Returns: Response[EventResponse]

• Access data: response.data.event_id, response.data.timestamp, etc.
• Check success: if response.ok:

Important Notes:

• Before tracking events, define them at https://xr2.uk/analytics/events
• Set event name and required/optional fields in the dashboard
• Field validation happens automatically based on your event definitions
• Events are deduplicated by trace_id + event_name