endorlabs 0.4.0

Type-safe Python SDK for the Endor Labs REST API — resource facades, operational workflows, and optional agent-context bootstrap

Endor Labs SDK

AURI platform · Platform docs · Quick start

Python CI

Type-safe, resource-oriented Python client for the Endor Labs REST API. List, get, create, update, and delete resources (projects, findings, scan results, policies, namespaces, and the rest of the registry-backed resource set) with consistent patterns for filtering, pagination, namespace traversal, and IDE-friendly typed facades.

• Python: 3.12+ (CI gates run on 3.13 — see CONTRIBUTORS.md)
• API spec: OpenAPI (Swagger)

Start here

You want to…	Go to
Use the SDK (API scripts, CI)	Installation → Quick start — no init() required
Bootstrap an AI agent (skills, offline OpenAPI)	AGENTS.md
Try the SDK on a real tenant	docs/guides/examples.md · Try it with skills
SDK contracts and deep reference	docs/README.md
Contribute to this repo	CONTRIBUTORS.md

Installation

pip install endorlabs

Or with uv:

uv add endorlabs

From the repository (editable):

git clone https://github.com/endorlabs/endorlabs-sdk.git
cd endorlabs-sdk
uv sync
# or: pip install -e .

Verify: uv run python -c "import endorlabs; print(endorlabs.__version__)"

Source repo: endorlabs/endorlabs-sdk — PyPI distribution name is endorlabs (import endorlabs).

Optional extras

Extra	Install	Enables
docs	pip install 'endorlabs[docs]'	User-docs sync (include_user_docs=True); OpenAPI download works on the base install
analytics	pip install 'endorlabs[analytics]'	DataFrame / Parquet export and estate graph metrics — see docs/estate/README.md

CSV export from workflows.estate.analyze.cardinality.tabular works without extras. In this repo: uv sync --extra docs --extra analytics.

Quick start

SDK-only — examples below do not call endorlabs.init(). For agent bootstrap, see AGENTS.md.

Entry point: endorlabs.Client(tenant=...). Resources are PascalCase facades (client.Project, client.Finding, …) matching endorctl api … --resource <Kind>.

Basic usage

import os
import endorlabs

client = endorlabs.Client(
    tenant=os.getenv("ENDOR_NAMESPACE", "your-tenant.namespace"),
    logging_level="ERROR",
)

namespaces = client.Namespace.list(traverse=True)
projects = client.Project.list(traverse=True, max_pages=1)

if projects:
    project = client.Project.get(projects[0].uuid)
    print(project.meta.name)

List field masks: a non-empty mask= on list() returns list[dict] wire JSON rows, not full Pydantic models. Omit mask when you need typed resources end-to-end. See docs/guides/consumer-ux-list-update.md.

Large estate lists: for project-scoped resources at scale, use endorlabs.tools.list_sharding or the endor-estate workflow CLI (see docs/contributing/list-query-performance.md).

Requesting a scan and waiting for results

repo_url = "https://github.com/tgowan-endor/BenchmarkJava.git"
projects = client.Project.search_by_name(repo_url, traverse=True, max_pages=2)
project = projects[0] if projects else None

client.Project.update(project, scan_state="SCAN_STATE_REQUEST_FULL_RESCAN")

client.wait_until(
    lambda: (
        (p := client.Project.get(project))
        and p.processing_status.scan_state == "SCAN_STATE_IDLE"
    ),
    timeout=300,
)

scans = client.ScanResult.list_by_project(project, limit=1)
latest_scan = scans.values[0] if scans.values else None
findings = client.Finding.list_for_context(latest_scan, max_pages=1) if latest_scan else None

Relationship accessors — prefer generated helpers over hand-built filters when the edge exists in the contract (list_by_project, list_for_context, Finding.to_dependency_metadata). They return RouteResult (use .values / .value). Catalog: docs/generated-reference/resource-routes.md · guide: docs/guides/facade-helpers.md.

More patterns (filters, F(), masks, namespace scoping): docs/guides/consumer-ux-list-update.md, docs/guides/retrieving-scan-results.md.

Transport-only APIClient

from endorlabs import APIClient

client = APIClient()
response = client.get("v1/namespaces/tenant.namespace/projects")

Prefer endorlabs.Client for typed models and namespace handling.

Configuration

The SDK uses environment variables only (no config file loading). Precedence: constructor arguments → environment variables → built-in defaults.

Variable	Purpose
ENDOR_API	API base URL (default: https://api.endorlabs.com)
ENDOR_API_CREDENTIALS_KEY	API key
ENDOR_API_CREDENTIALS_SECRET	API secret
ENDOR_TOKEN	Bearer token; validated first when set
ENDOR_NAMESPACE	Default tenant namespace (e.g. tenant.namespace)
ENDOR_LOG_LEVEL	Optional: DEBUG, INFO, WARNING, ERROR, CRITICAL
ENDOR_MAX_RETRIES	Optional: retry count (default: 5)

Canonical naming is tenant.namespace.child; do not use UUIDs in namespace paths. Full semantics: docs/contracts.md.

Example .env for local runs:

ENDOR_API_CREDENTIALS_KEY=your-api-key
ENDOR_API_CREDENTIALS_SECRET=your-api-secret
ENDOR_NAMESPACE=your-tenant.namespace
ENDOR_LOG_LEVEL=INFO

Browser auth, SSO setup, and skill walkthroughs: docs/guides/examples.md.

Try it with skills

Guided tenant sessions use shipped agent skills — start with docs/guides/examples.md and AGENTS.md. Skills ship in the wheel (endorlabs.agent_knowledge_index_path()) or .endorlabs-context/sdk/skills/ after init().

Further reading

• SDK docs: docs/README.md — contracts, guides, generated reference, errors
• API surfaces: docs/reference/api-surfaces.md
• Architecture (contributors): docs/contributing/architecture.md
• Agents: AGENTS.md — bootstrap, workflows inventory, naming
• Contribute: CONTRIBUTORS.md · devtools/README.md

License

MIT. See LICENSE.