OpenAPI

openapi

OpenAPI specification handling for T3 API endpoints.

CollectionEndpoint

Bases: TypedDict

Type definition for a collection endpoint.

Attributes:

Name	Type	Description
path	str	The URL path of the endpoint (e.g. /v2/packages/active).
method	str	The HTTP method in uppercase (e.g. GET).
name	str	A user-friendly display name derived from the summary or path.
category	str	The grouping category derived from tags or path segments.
description	str	A human-readable description of what the endpoint returns.

fetch_openapi_spec

fetch_openapi_spec() -> Dict[str, Any]

Fetch the OpenAPI specification from the live T3 API.

Returns:

Type	Description
Dict[str, Any]	The parsed OpenAPI specification as a dictionary.

Raises:

Type	Description
SystemExit	If the API cannot be reached or returns invalid data.

Source code in t3api_utils/openapi/spec_fetcher.py

def fetch_openapi_spec() -> Dict[str, Any]:
    """
    Fetch the OpenAPI specification from the live T3 API.

    Returns:
        The parsed OpenAPI specification as a dictionary.

    Raises:
        SystemExit: If the API cannot be reached or returns invalid data.
    """
    api_host = config_manager.get_api_host()
    spec_url = f"{api_host}/v2/spec/openapi.json"

    console.print(f"Fetching OpenAPI spec from {spec_url}...")

    try:
        with httpx.Client(timeout=30.0) as client:
            response = client.get(spec_url)
            response.raise_for_status()

        spec: Dict[str, Any] = response.json()
        console.print("✓ OpenAPI spec fetched successfully")
        return spec

    except httpx.HTTPError as e:
        console.print(f"✗ Failed to fetch OpenAPI spec: {e}")
        sys.exit(1)
    except Exception as e:
        console.print(f"✗ Error parsing OpenAPI spec: {e}")
        sys.exit(1)

get_collection_endpoints

get_collection_endpoints() -> List[CollectionEndpoint]

Fetch and parse collection endpoints from the live API.

Convenience function that fetches the OpenAPI spec and extracts all paginated collection endpoints in a single call.

Returns:

Type	Description
List[CollectionEndpoint]	A list of CollectionEndpoint dicts describing each available
List[CollectionEndpoint]	collection.

Raises:

Type	Description
SystemExit	If the API spec cannot be fetched or contains no collection endpoints.

Source code in t3api_utils/openapi/spec_fetcher.py

def get_collection_endpoints() -> List[CollectionEndpoint]:
    """Fetch and parse collection endpoints from the live API.

    Convenience function that fetches the OpenAPI spec and extracts all
    paginated collection endpoints in a single call.

    Returns:
        A list of ``CollectionEndpoint`` dicts describing each available
        collection.

    Raises:
        SystemExit: If the API spec cannot be fetched or contains no
            collection endpoints.
    """
    spec = fetch_openapi_spec()
    return parse_collection_endpoints(spec)

pick_collection

pick_collection() -> CollectionEndpoint

Interactive picker for selecting a collection endpoint.

Returns:

Type	Description
CollectionEndpoint	The selected collection endpoint.

Raises:

Type	Description
SystemExit	If user cancels or no endpoints are available.

Source code in t3api_utils/openapi/collection_picker.py

def pick_collection() -> CollectionEndpoint:
    """
    Interactive picker for selecting a collection endpoint.

    Returns:
        The selected collection endpoint.

    Raises:
        SystemExit: If user cancels or no endpoints are available.
    """
    endpoints = get_collection_endpoints()

    # Group endpoints by category
    categories = _group_by_category(endpoints)

    if len(categories) == 1:
        # If only one category, show endpoints directly
        category_name = list(categories.keys())[0]
        return _pick_from_category(category_name, categories[category_name])
    else:
        # Multiple categories, let user pick category first
        selected_category = _pick_category(categories)
        return _pick_from_category(selected_category, categories[selected_category])