Client

Initialize and configure the Docent client

The Docent class is the main entry point for the SDK. All API operations are methods on this client.

Initialization

from docent import Docent

# Minimal — reads API key from a discovered config file or environment
client = Docent()

# With explicit configuration
client = Docent(
    api_key="your-api-key",
    collection_id="my-default-collection",
)

Constructor Parameters

api_key · str | None

API key for authentication. Falls back to the discovered config file (~/.docent/docent.env when no project-level file is found), then the DOCENT_API_KEY environment variable. See the configuration priority table for the full resolution order. Required unless one AWS authentication mode is enabled.

aws_oidc_identity · bool · default: "False"

Authenticate with an AWS outbound OIDC token. The active IAM role and its account-specific issuer must be connected to a Docent service account. This is the preferred AWS workload authentication mode.

aws_federated_identity · bool · default: "False"

Authenticate with the legacy audience-bound signed STS request protocol. Use only for an existing service-account binding without an OIDC issuer.

aws_profile · str | None

Optional named AWS profile used by either AWS authentication mode.

aws_region · str | None

Optional regional STS endpoint for AWS authentication. Outbound OIDC does not work through the global STS endpoint.

api_key, aws_oidc_identity=True, and aws_federated_identity=True are mutually exclusive. The client raises ValueError if more than one is set.

collection_id · str | None

Stored as default_collection_id for your convenience, but SDK methods do not fall back to it automatically — you must pass collection_id explicitly to each method call. Falls back to DOCENT_COLLECTION_ID from the config file.

api_url · str | None

Direct URL of the Docent API server. Overrides URL derived from domain. Falls back to DOCENT_API_URL environment variable.

frontend_url · str | None

Direct URL of the Docent frontend UI. Overrides URL derived from domain. Falls back to DOCENT_FRONTEND_URL environment variable.

domain · str | None · default: "docent.transluce.org"

Domain of the Docent instance. API and frontend URLs are derived as https://api.{domain} and https://{domain} unless overridden.

use_https · bool · default: "True"

Whether to use HTTPS when constructing URLs from the domain.

config_file · str | Path | None

Explicit path to a dotenv config file. If not provided, the SDK searches for project-level docent.env overrides from the current directory upward, then checks the default global config file at ~/.docent/docent.env.

log_stream · IO[str] | None

Output stream for SDK log messages. Defaults to sys.stdout.

Properties

frontend_url · str

The resolved Docent frontend base URL.

backend_url · str

The resolved Docent API base URL.

default_collection_id · str | None

The default collection ID, if configured.

Example: Full Configuration

from docent import Docent

client = Docent(
    api_key="your-api-key",
    collection_id="my-collection",
    api_url="https://api.my-docent.example.com",
    frontend_url="https://my-docent.example.com",
)

print(client.frontend_url)  # https://my-docent.example.com
print(client.backend_url)   # https://api.my-docent.example.com/rest

See Authentication for AWS workload examples and deployment prerequisites.