NocoDB Simple Client

1.3.2 · active · verified Thu Apr 16

A simple and powerful Python client for the NocoDB REST API, allowing interaction with NocoDB projects, tables, and records. It handles API authentication and provides a Pythonic interface for CRUD operations. The current version is 1.3.2, and it follows NocoDB's API changes with new releases.

Common errors

```
NocoDB API Error: {'msg': 'Project not found', 'status': 404}
```
cause The provided `project_id` does not exist or the `auth_token` does not have access to it.

fix Verify that your `NOCODB_PROJECT_ID` is correct and that your `NOCODB_AUTH_TOKEN` has the necessary permissions for that project. Check the NocoDB UI for the exact project ID and token.
```
NocoDB API Error: {'msg': 'Authentication failed', 'status': 401}
```
cause The `auth_token` is incorrect, expired, or missing.

fix Ensure your `NOCODB_AUTH_TOKEN` is the correct `X-NocoDB-Auth` token (global API token) for your NocoDB instance and is still valid. Regenerate it if necessary.
```
NocoDB API Error: {'msg': 'Table not found', 'status': 404}
```
cause The specified table name does not exist in the project or is misspelled, or the `auth_token` lacks permissions to access it.

fix Check the exact spelling and case of the table name. Verify the table exists in the NocoDB project associated with the `project_id` and that the provided `auth_token` has access.
```
KeyError: 'some_field_name'
```
cause Trying to access a field name that doesn't exist or has a different case in the NocoDB record response.

fix Inspect the structure of the record object returned by NocoDB to confirm the exact field names and their casing (e.g., `print(records[0])`). NocoDB field names are case-sensitive.

Warnings

breaking The client adapts to NocoDB API changes. Client versions 1.2.0+ support NocoDB v0.90.0+ APIs, and 1.3.0+ support NocoDB v0.103.0+. Older client versions or older NocoDB instances may lead to API incompatibility.
Fix: Ensure your `nocodb-simple-client` version is compatible with your NocoDB backend version. Consult the client's release notes and NocoDB's changelog to match versions.
gotcha When performing `update` or `delete` operations, NocoDB requires its internal record ID (e.g., `rec_xxxxxxxxxxxxxx`), not a custom primary key from your table.
Fix: Always retrieve the NocoDB record ID (often named `id` or `uuid` in the NocoDB response) from a `get` operation before attempting `update` or `delete`.
gotcha Incorrect `base_url`, `auth_token`, or `project_id` will lead to authentication failures or 'Project not found' errors. The `auth_token` must be the `X-NocoDB-Auth` token from your NocoDB instance, not a personal access token.
Fix: Double-check that `NOCODB_BASE_URL` points to your NocoDB instance, `NOCODB_AUTH_TOKEN` is the correct global `X-NocoDB-Auth` token, and `NOCODB_PROJECT_ID` is your project's internal ID. Ensure the NocoDB server is running and accessible.

Install

pip install nocodb-simple-client Install latest version

Imports

NocoDBClient

from nocodb_simple_client import NocoDBClient

Quickstart

Initializes the NocoDB client using environment variables for sensitive details, then lists tables and fetches records from an example table. This helps verify basic connectivity and authentication.

import os
from nocodb_simple_client import NocoDBClient

# It is recommended to use environment variables for sensitive data
BASE_URL = os.environ.get("NOCODB_BASE_URL", "http://localhost:8080")
AUTH_TOKEN = os.environ.get("NOCODB_AUTH_TOKEN", "YOUR_AUTH_TOKEN_HERE") # X-NocoDB-Auth token
PROJECT_ID = os.environ.get("NOCODB_PROJECT_ID", "p00000000000000000000000000") # Replace with your actual Project ID

try:
    client = NocoDBClient(
        base_url=BASE_URL,
        auth_token=AUTH_TOKEN,
        project_id=PROJECT_ID
    )

    # Example: List all tables in the project
    # This requires the AUTH_TOKEN and PROJECT_ID to be valid.
    tables_response = client.tables.list()
    print(f"Tables in project: {[t['title'] for t in tables_response.get('list', [])]}")

    # Example: Get records from a specific table
    # Replace 'MyTable' with an actual table name from your NocoDB project
    TABLE_NAME = os.environ.get("NOCODB_EXAMPLE_TABLE", "TestTable")
    print(f"\nAttempting to fetch records from table: {TABLE_NAME}")
    records = client.tables.get_all(TABLE_NAME)
    print(f"First 3 records from {TABLE_NAME}: {records[:3]}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure NOCODB_BASE_URL, NOCODB_AUTH_TOKEN, and NOCODB_PROJECT_ID are correctly set.")
    print("Also verify the NOCODB_EXAMPLE_TABLE exists and is accessible by the provided token.")

view raw JSON →