> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/sdks/python.md).

# Python

Write and read records from Python with the Norbix Python SDK.

The Python SDK is [`norbix`](https://pypi.org/project/norbix/) on PyPI (source: [github.com/norbix-code/sdk-python](https://github.com/norbix-code/sdk-python)). It needs Python 3.10 or newer. You install `norbix` and import `norbix_python`.

This page was run on 2026-10-06 with `norbix` **3.12.0** and Python 3.14. All the code below is one file, `quickstart.py`: put the blocks one after the other.

## Before you start

* A project with a `books` collection — `title` (text, required), `pages` (number, required), `in_stock` (yes / no), `genre`. Create it in Cloud as in step 3 of the [Quickstart](/codemash/get-started/managed-service/quickstart.md).
* A key and your project id in `NORBIX_API_KEY` and `NORBIX_PROJECT_ID` — see [Install a Norbix SDK](/codemash/sdks/install.md). The key needs a role that may write records, for example **Data Editor**.

## Install

```sh
pip install norbix
```

## Create the client

```python
import json

from norbix_python import Norbix, NorbixError

# Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
norbix = Norbix()
```

`norbix.api` is the data part (records, files, users), `norbix.hub` the configuration part (schemas, integrations, templates). To pass the values in code instead: `Norbix(api_key="nbsu_…", project_id="pr_…")`. For `asyncio`, use `AsyncNorbix` — the same methods, awaited.

## Write a record

A record goes in as a JSON string in `document`. The answer is a `dict` with the new record's `id`.

```python
# Write: add one book to the `books` collection.
created = norbix.api.database.insert_one(
    "books",
    document=json.dumps({"title": "Dune", "pages": 412, "genre": "fiction"}),
)
print("Inserted", created["id"])
```

## Read records

`find` returns one page of records in `["list"]["items"]`. Other request fields (`filter`, `sort`, `projection`, `pageSize`, …) are keyword arguments with the API's names — see [Search parameters](/codemash/cloud/concepts/search-parameters.md).

```python
# Read: find the books.
found = norbix.api.database.find("books", pageSize=10)
for book in found["list"]["items"]:
    print(f"{book['title']} — {book['pages']} pages")
```

## Handle errors

A failed call raises `NorbixError` with the gateway's `code` and `message`, the HTTP `status`, and every error in `errors`. Here the schema says `pages` is required:

```python
# Error handling: the schema requires `pages`, so this insert fails.
try:
    norbix.api.database.insert_one("books", document=json.dumps({"title": "Untitled draft"}))
except NorbixError as err:
    print(f"Failed: {err.code} — {err.message}")
```

The SDK also has `AuthenticationError`, `NotFoundError`, `RateLimitError` and `ValidationError` (all subclasses of `NorbixError`).

## Run it

```sh
python quickstart.py
```

The output (the collection already had *The Hobbit*):

```
Inserted 6ac54bbb212c29912eaddd93
Dune — 412 pages
The Hobbit — 310 pages
Failed: CM-ERRORS-DATABASE-030 — Field 'pages' is invalid: a value is required
```

## Next steps

* Every operation, with a tab per language: [SDK reference](/codemash/sdks/database.md).
* The same calls from the terminal: [CLI](/codemash/cli/cli.md).