Configuration.
Constructor options, config fields, and per-instance isolation.
MatildaClient
client = MatildaClient(
token="", # static Bearer JWT
# keyword-only below:
base_url=DEFAULT_BASE_URL, # https://matilda.maincode.com/api
get_token=None, # async token provider
config=None, # or pass a pre-built MatildaConfig
)| Field | type | description |
|---|---|---|
| token | str | A static access token. Use this for simple setups, or use get_token for managed refresh. Defaults to the empty string. |
| base_url | str | The Matilda API base URL. Must be absolute for auth flows. Defaults to https://matilda.maincode.com/api. |
| get_token | TokenProvider | Async token provider called on every request (and once with force_refresh=True after a 401, before the single retry). A managed TokenManager is wired here automatically after client.auth.login_with_*. |
| config | MatildaConfig | A pre-built config. When omitted, one is constructed from the other parameters. |
MatildaConfig
A frozen dataclass — create a new client to change configuration.
| Field | type | description |
|---|---|---|
| base_url | str | The Matilda API base URL. Defaults to https://matilda.maincode.com/api. |
| token | str | Static Bearer token. Defaults to the empty string. |
| get_token | TokenProvider | None | Async token provider (see above). |
| timeout | float | Request timeout in seconds. Defaults to 120.0. |
| api_version | str | API version sent via the X-Matilda-API-Version header. Defaults to MATILDA_CURRENT_API_VERSION. |
| chunk_size | int | Chunked-upload part size in bytes. Defaults to 8388608 (8 MiB). |
| chunked_threshold | int | File size at/above which uploads switch to the chunked protocol. Defaults to 16777216 (16 MiB). |
| part_concurrency | int | Parallel parts per chunked upload. Defaults to 4. |
| max_part_retries | int | Retries per upload part before the session is aborted. Defaults to 3. |
Environment URLs
| Environment | Base URL |
|---|---|
| Production | https://matilda.maincode.com/api |
| Staging | https://staging.matilda.maincode.com/api |
Instance isolation
Each MatildaClient instance holds its own independent config. Multiple instances in the same process are fully isolated — constructor options are scoped to that instance.
staging = MatildaClient(base_url="https://staging.matilda.maincode.com/api")
prod = MatildaClient(base_url="https://matilda.maincode.com/api")
print(staging.config.base_url) # https://staging.matilda.maincode.com/api
print(prod.config.base_url) # https://matilda.maincode.com/apiconfig (attribute)
Returns the current MatildaConfig.
cfg = client.config
print(cfg.base_url, cfg.token)origin (config property)
The scheme+host of base_url — the origin where core-auth endpoints live. Auth flows resolve endpoints against config.origin, so base_url must be an absolute URL:
client.config.origin # e.g. "https://matilda.maincode.com"