Skip to content

Using the Generated lakeFS SDK

The generated Python SDK gives you direct access to the lakeFS API from the OpenAPI specification that the server publishes. This low-level SDK hands you complete control over API interactions and is useful when you need capabilities not covered by the High-Level SDK, or when you prefer working directly with the API.

Because each lakeFS edition serves its own API surface, the generated SDK is published as one package per edition. Both come out of the same OpenAPI generator and share the same client shape, so the package you install follows the lakeFS you run rather than the way you intend to write your code.

When to Use

Use the generated SDK when you:

  • Need low-level API access with full control over requests
  • Want to use features not available in the High-Level SDK
  • Prefer direct API interaction patterns
  • Need to access all API endpoints programmatically

Info

For most common lakeFS operations (branches, tags, commits, objects), the High-Level SDK is recommended as it provides a more Pythonic interface.

Choosing a Package for Your lakeFS Edition and Version

Start from the lakeFS you are talking to, since the edition it runs decides which package can describe its API:

Package Use it against Import name Python API reference
lakefs-enterprise-sdk lakeFS Enterprise, self-managed or hosted lakefs_enterprise_sdk 3.10 and above pydocs-enterprise-sdk.lakefs.io
lakefs-sdk lakeFS Community lakefs_sdk 3.7 and above pydocs-sdk.lakefs.io

For everything the editions share, the two packages are the same client under a different module name, which is why every example on this page carries an Enterprise tab and a Community tab whose only difference is that module name. The Enterprise package then adds the API groups that only lakeFS Enterprise serves, which are covered under Enterprise-only API Groups. Pick the tab for your edition once and every other tabbed block on this page follows your choice.

lakefs-enterprise-sdk is available in lakeFS Enterprise and its use is governed by the Enterprise SDK License. Start a free trial.

Match the Package Version to Your lakeFS Version

Each package is regenerated from the OpenAPI specification its own edition publishes, at every release of that edition, and it is versioned to match. A new feature therefore reaches the generated SDK of the variant and version that introduced it, so an endpoint added in a given lakeFS Enterprise release appears in lakefs-enterprise-sdk at that same version, and the two editions advance on their own version lines rather than in step with each other.

Install the package version that corresponds to your server, and pin it in your requirements so an unrelated upgrade cannot move the client out from under a running server:

pip install "lakefs-enterprise-sdk==<your lakeFS Enterprise version>"

pip install "lakefs-sdk==<your lakeFS Community version>"

A client older than your server simply lacks the newest methods, which is harmless as long as you do not need them. A client newer than your server is the case to watch, because methods generated for endpoints your version does not serve yet are present in Python and fail only when called, in the same way that reaching for an Enterprise-only group against lakeFS Community does. When a call fails for no apparent reason, compare your package version against your server version before anything else. Which version introduced a given capability is recorded in the lakeFS Enterprise release notes, and in the lakeFS Community releases for the Community package.

Install only one of the two packages in a given environment. They declare separate top-level modules and can technically sit side by side, but holding clients from both makes it hard to tell which API surface any given call belongs to.

Installation

Install the package for your edition using pip:

pip install lakefs-enterprise-sdk

Or upgrade to the latest version:

pip install --upgrade lakefs-enterprise-sdk

pip install lakefs-sdk

Or upgrade to the latest version:

pip install --upgrade lakefs-sdk

Basic Setup

Initializing the SDK

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.rest import ApiException

# Configure the API client
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

# Create an API client
api_client = lakefs_enterprise_sdk.ApiClient(configuration)

import lakefs_sdk
from lakefs_sdk.rest import ApiException

# Configure the API client
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

# Create an API client
api_client = lakefs_sdk.ApiClient(configuration)

Authentication Options

The SDK supports multiple authentication methods:

import lakefs_enterprise_sdk
import os

# HTTP Basic Authentication
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username=os.environ["LAKEFS_ACCESS_KEY"],
    password=os.environ["LAKEFS_SECRET_KEY"]
)

# JWT Bearer Token
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    access_token=os.environ["LAKEFS_TOKEN"]
)

api_client = lakefs_enterprise_sdk.ApiClient(configuration)

import lakefs_sdk
import os

# HTTP Basic Authentication
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username=os.environ["LAKEFS_ACCESS_KEY"],
    password=os.environ["LAKEFS_SECRET_KEY"]
)

# JWT Bearer Token
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    access_token=os.environ["LAKEFS_TOKEN"]
)

api_client = lakefs_sdk.ApiClient(configuration)

Simple Examples

List Repositories

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
        for repo in response.results:
            print(f"Repository: {repo.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
        for repo in response.results:
            print(f"Repository: {repo.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

Get Repository Details

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)
    repository = "my-repo"

    try:
        repo = api_instance.get_repository(repository)
        print(f"Repository: {repo.id}")
        print(f"Storage: {repo.storage_namespace}")
        print(f"Created: {repo.creation_date}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)
    repository = "my-repo"

    try:
        repo = api_instance.get_repository(repository)
        print(f"Repository: {repo.id}")
        print(f"Storage: {repo.storage_namespace}")
        print(f"Created: {repo.creation_date}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

List Branches

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.branches_api import BranchesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = BranchesApi(api_client)
    repository = "my-repo"

    try:
        response = api_instance.list_branches(repository)
        for branch in response.results:
            print(f"Branch: {branch.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

import lakefs_sdk
from lakefs_sdk.api.branches_api import BranchesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = BranchesApi(api_client)
    repository = "my-repo"

    try:
        response = api_instance.list_branches(repository)
        for branch in response.results:
            print(f"Branch: {branch.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

Create a Commit

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.commits_api import CommitsApi
from lakefs_enterprise_sdk.models.commit_creation import CommitCreation

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = CommitsApi(api_client)
    repository = "my-repo"
    branch = "main"

    commit_creation = CommitCreation(
        message="My commit message",
        metadata={"author": "data-team"}
    )

    try:
        commit = api_instance.commit(repository, branch, commit_creation)
        print(f"Committed: {commit.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

import lakefs_sdk
from lakefs_sdk.api.commits_api import CommitsApi
from lakefs_sdk.models.commit_creation import CommitCreation

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = CommitsApi(api_client)
    repository = "my-repo"
    branch = "main"

    commit_creation = CommitCreation(
        message="My commit message",
        metadata={"author": "data-team"}
    )

    try:
        commit = api_instance.commit(repository, branch, commit_creation)
        print(f"Committed: {commit.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

Error Handling

Handle API errors using ApiException:

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi
from lakefs_enterprise_sdk.rest import ApiException

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
    except ApiException as e:
        if e.status == 401:
            print("Unauthorized - check credentials")
        elif e.status == 404:
            print("Resource not found")
        else:
            print(f"API Error: {e.reason}")

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi
from lakefs_sdk.rest import ApiException

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
    except ApiException as e:
        if e.status == 401:
            print("Unauthorized - check credentials")
        elif e.status == 404:
            print("Resource not found")
        else:
            print(f"API Error: {e.reason}")

Enterprise-only API Groups

Available in lakeFS Enterprise. Start a free trial.

Alongside the shared API classes such as ActionsApi, AuthApi, BranchesApi, CommitsApi, ObjectsApi, PullsApi, RefsApi, RepositoriesApi, StagingApi and TagsApi, the lakefs_enterprise_sdk module exposes these groups that have no counterpart in the Community package:

API class Covers
DatasetsApi The named, versioned views described under Datasets, including their versions, metadata keys and pull requests
TenantsApi Tenant management

These groups appear only in the Enterprise tabs, since the Community package neither exposes the classes nor talks to a server that serves them. Calling one follows the same pattern as any other API class, so listing the datasets in an installation reads as an ordinary paged call:

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.datasets_api import DatasetsApi
from lakefs_enterprise_sdk.rest import ApiException

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = DatasetsApi(api_client)

    try:
        response = api_instance.list_datasets(amount=100)
        for dataset in response.results:
            print(f"Dataset: {dataset.id}")
    except ApiException as e:
        print(f"Error: {e}")

Full API Reference

For complete API documentation and method signatures, see the reference for the package you installed: