Skip to main content

keyban_api_client

Keyban API Client

A Python client library for interacting with the Keyban API Product management. This library provides a simple and intuitive interface for managing products in your applications.

keyban_api_client._version

Version information for keyban-api-client.

keyban_api_client.client

Keyban API Product Python Client

A Python client for interacting with the Keyban API Product API. This client provides methods for CRUD operations on products.

ProductData Objects​

class ProductData(BaseModel)

Product data following schema.org/Product format with custom field support

name​

Keep name required for practical use

image​

URL to product image

gtin​

Global Trade Item Number

sku​

Stock Keeping Unit

brand​

Brand info

countryOfOrigin​

Country where product is made

keywords​

Array of keywords

Config Objects​

class Config()

extra​

Allow custom fields via ** syntax

__init__​

def __init__(confidential_paths: Optional[List[str]] = None,
             enc_algorithm: str = "sha256",
             enc_key: Optional[str] = None,
             **data)

Initialize ProductData with optional encryption of confidential fields

Arguments:

  • confidential_paths - List of field paths to encrypt
  • enc_algorithm - "sha256" or "aes-256-gcm" (default: "sha256")
  • enc_key - Base64-encoded encryption key (auto-generated if not provided)
  • **data - Product data fields

model_dump​

def model_dump(**kwargs)

Custom serialization to exclude null values

parse_brand​

@field_validator('brand', mode='before')
@classmethod
def parse_brand(cls, v)

Handle brand as either string or object with name field

parse_country_of_origin​

@field_validator('countryOfOrigin', mode='before')
@classmethod
def parse_country_of_origin(cls, v)

Handle countryOfOrigin as either string or object with identifier/name

encryption_key​

@property
def encryption_key() -> Optional[str]

Get the encryption key used (if any)

Application Objects​

class Application(BaseModel)

Application model

Product Objects​

class Product(BaseModel)

Keyban API Product model

application​

Handle both object and UUID formats

network​

Network enum value

status​

ProductStatus enum value

parse_application​

@field_validator('application', mode='before')
@classmethod
def parse_application(cls, v)

Handle both Application object and UUID string formats

CreateProductRequest Objects​

class CreateProductRequest(BaseModel)

Request model for creating a product

validate_network​

@field_validator('network')
@classmethod
def validate_network(cls, v)

Only StarknetSepolia network is currently supported

UpdateProductRequest Objects​

class UpdateProductRequest(BaseModel)

Request model for updating a product

validate_network​

@field_validator('network')
@classmethod
def validate_network(cls, v)

Only StarknetSepolia network is currently supported

ProductListResponse Objects​

class ProductListResponse(BaseModel)

Response model for listing products

FilterOperator Objects​

class FilterOperator(BaseModel)

Filter operator for querying

operator​

'eq', 'contains', 'gt', 'lt'

QueryParams Objects​

class QueryParams(BaseModel)

Query parameters for listing products

ProductClient Objects​

class ProductClient()

Python client for interacting with Keyban API Product endpoints.

Supports the following operations:

  • List products with flexible filtering and pagination
  • Get a specific product by ID
  • Create a new product
  • Update an existing product
  • Delete an existing product

The list_products() method supports flexible filtering using FilterOperator objects. Supported filter fields: status, network, data.name, data.brand, data.category, createdAt, updatedAt, application.id Supported operators: eq (exact match), contains (substring), gt (greater than), lt (less than) Supported networks: StarknetSepolia (default)

__init__​

def __init__(base_url: str,
             api_key: str,
             api_version: str = "v1",
             timeout: int = 30)

Initialize the Keyban API Product client.

Arguments:

  • base_url - Base URL of the API (e.g., "https://api.keyban.io")
  • api_key - API key for authentication (required)
  • api_version - API version (default: "v1")
  • timeout - Request timeout in seconds (default: 30)

list_products​

def list_products(filters: Optional[List[FilterOperator]] = None,
                  current_page: int = 1,
                  page_size: int = 10) -> ProductListResponse

List products with flexible custom filtering.

This method provides full access to the filtering system, allowing you to filter by any field with any supported operator.

Arguments:

  • filters - List of FilterOperator objects for custom filtering (optional)
  • current_page - Page number (1-based, default: 1)
  • page_size - Number of items per page (default: 10, max: 100)

Returns:

ProductListResponse containing the list of products and total count

Supported filter fields:

  • status: Product status (DRAFT, ACTIVE, etc.)
  • network: Network type (StarknetSepolia)
  • data.name: Product name
  • data.brand: Product brand
  • data.category: Product category
  • data.description: Product description
  • createdAt: Creation date
  • updatedAt: Last update date
  • application.id: Application ID

Supported operators:

  • eq: Exact match
  • contains: Substring search (case-insensitive)
  • gt: Greater than (useful for dates)
  • lt: Less than (useful for dates)

Examples:

List all products (no filters)

all_sheets = client.list_products()

Filter by application ID

app_filter = FilterOperator(field="application.id", operator="eq", value=str(app_id)) sheets = client.list_products(filters=[app_filter])

Filter by product name (substring search)

name_filter = FilterOperator(field="data.name", operator="contains", value="Nike") sheets = client.list_products(filters=[name_filter])

Filter by status and network

filters = [ FilterOperator(field="status", operator="eq", value="ACTIVE"), FilterOperator(field="network", operator="eq", value="StarknetSepolia"), FilterOperator(field="data.brand", operator="contains", value="Nike") ] sheets = client.list_products(filters=filters)

Filter by date range (created in last 7 days)

from datetime import datetime, timedelta week_ago = (datetime.now() - timedelta(days=7)).isoformat() date_filter = FilterOperator(field="createdAt", operator="gt", value=week_ago) recent_sheets = client.list_products(filters=[date_filter])

Complex filtering: Active Nike products created this year

from datetime import datetime year_start = datetime(2024, 1, 1).isoformat() filters = [ FilterOperator(field="status", operator="eq", value="ACTIVE"), FilterOperator(field="data.brand", operator="eq", value="Nike"), FilterOperator(field="createdAt", operator="gt", value=year_start) ] nike_products = client.list_products(filters=filters, page_size=50)

get_product​

def get_product(product_id: UUID) -> Product

Get a specific product by its ID.

This endpoint is public and doesn't require authentication.

Arguments:

  • product_id - The UUID of the product

Returns:

Product object

Raises:

  • requests.HTTPError - If the product is not found (404) or other HTTP errors

create_product​

def create_product(product_data: CreateProductRequest) -> Product

Create a new product.

Requires authentication and organization-level access.

Arguments:

  • product_data - The product data to create

Returns:

Created Product object

Raises:

  • requests.HTTPError - If the application is not found (404) or other HTTP errors

update_product​

def update_product(product_id: UUID,
                   update_data: UpdateProductRequest) -> Product

Update an existing product.

Requires authentication and organization-level access. Only products belonging to the authenticated organization can be updated.

Arguments:

  • product_id - The UUID of the product to update
  • update_data - The updated product data

Returns:

Updated Product object

Raises:

  • requests.HTTPError - If the product is not found (404) or other HTTP errors

delete_product​

def delete_product(product_id: UUID) -> bool

Delete an existing product.

Requires authentication and organization-level access. Only products belonging to the authenticated organization can be deleted.

Arguments:

  • product_id - The UUID of the product to delete

Returns:

  • bool - True if deletion was successful

Raises:

  • requests.HTTPError - If the product is not found (404) or other HTTP errors

close​

def close()

Close the HTTP session

create_filter​

def create_filter(field: str, operator: str, value: Any) -> FilterOperator

Create a FilterOperator for use with list_products.

Arguments:

  • field - Field to filter on (e.g., "status", "network", "data.name")
  • operator - Filter operator ("eq", "contains", "gt", "lt")
  • value - Value to filter by

Returns:

FilterOperator object

Examples:

Exact match filters

status_filter = create_filter("status", "eq", "ACTIVE") network_filter = create_filter("network", "eq", "StarknetSepolia") app_filter = create_filter("application.id", "eq", str(app_id))

Substring search filters

name_filter = create_filter("data.name", "contains", "Product") brand_filter = create_filter("data.brand", "contains", "Nike") category_filter = create_filter("data.category", "eq", "Clothing")

Date range filters

from datetime import datetime, timedelta week_ago = (datetime.now() - timedelta(days=7)).isoformat() recent_filter = create_filter("createdAt", "gt", week_ago)

Multiple filters example

filters = [ create_filter("status", "eq", "ACTIVE"), create_filter("data.brand", "eq", "Nike"), create_filter("createdAt", "gt", "2024-01-01T00:00:00Z") ] sheets = client.list_products(filters=filters)

search_products_by_application_id​

def search_products_by_application_id(client: ProductClient,
                                      application_id: UUID,
                                      page_size: int = 100) -> List[Product]

Convenience function to search for products by application ID.

Arguments:

  • client - ProductClient instance
  • application_id - Application ID to filter by
  • page_size - Number of results to return (default: 100)

Returns:

List of matching Product objects