Markdown

Quickbase

Quickbase is the client that everything else starts from. Use it as a context manager, so that its connections get closed. AsyncQuickbase takes the same options, except that http_client is an httpx.AsyncClient, and has the same methods, which you await where the examples show it.

The examples below use qb, made as shown here. A live test runs every example with both clients and checks its output.

SyncAsync

from pyquickbase import Quickbase

with Quickbase(
    realm="acme", token="your_user_token"
) as qb:
    print(qb.realm)

from pyquickbase import AsyncQuickbase

async with AsyncQuickbase(
    realm="acme", token="your_user_token"
) as qb:
    print(qb.realm)

Create and close a client

For the full picture, see Configuring clients.

Create a client

A Quickbase API client. Use it as a context manager so connections get closed.

Parameters

• realm str, required
  Your realm, as acme, acme.quickbase.com, or a realm URL.
• token str, required
  A Quickbase user token.
• base_url str, default 'https://api.quickbase.com/v1'
  The API root. Must use HTTPS, except for loopback addresses.

7 more: retry, timeout, user_agent, http_client, schema_ttl, policy, confirmation_key

• retry RetryPolicy | None, optional
  How to retry rate limits, connection failures, and reads that time out or get a 502, 503, or 504. A write isn't retried after anything that may have reached Quickbase.
• timeout float, default 30.0
  Seconds to allow for each step of a request, such as connecting or waiting for the response, as httpx applies it. Ignored if you pass http_client.
• user_agent str | None, optional
  Identifies your application, placed before the SDK's own User-Agent.
• http_client httpx.Client | None, optional
  Your own configured httpx client, for proxies, custom TLS, event hooks, or custom transports. You remain responsible for closing it.
• schema_ttl float, default 300.0
  Seconds to cache app, table, and field metadata. Use 0 to disable caching.
• policy Policy | BoundPolicy | None, optional
  What the client may do, as a BoundPolicy from Policy.bind(), or a Policy that names no table or field, such as Policy.read_only(). Every request is checked before it's sent, including through request(), and a refused one raises PolicyRefusedError. What the policy hides is left out of every response, so a hidden field acts as if it didn't exist. Without one, the client does whatever the token can.
• confirmation_key bytes | None, optional
  The secret that signs the confirmations an operation's preview returns, at least 32 random bytes, such as from secrets.token_bytes(32). Give several clients, or processes, the same key so that any of them accepts a preview another made. Without it, each client makes its own.

Raises

• ConfigurationError: realm, token, or base_url can't be used, or policy names tables or fields but isn't bound.

Quickbase(
    *,
    realm: str,
    token: str,
    base_url: str = "https://api.quickbase.com/v1",
    retry: RetryPolicy | None = None,
    timeout: float = 30.0,
    user_agent: str | None = None,
    http_client: httpx.Client | None = None,
    schema_ttl: float = 300.0,
    policy: Policy | BoundPolicy | None = None,
    confirmation_key: bytes | None = None,
)

Example

SyncAsync

from pyquickbase import Quickbase, Policy

with Quickbase(
    realm="acme",
    token="your_user_token",
    policy=Policy.read_only(),
) as qb:
    print(qb.realm)

from pyquickbase import AsyncQuickbase, Policy

async with AsyncQuickbase(
    realm="acme",
    token="your_user_token",
    policy=Policy.read_only(),
) as qb:
    print(qb.realm)

Output

acme.quickbase.com

Create a client from the environment

Create a client from the QB_REALM and QB_USER_TOKEN environment variables.

It takes the same options as the constructor, other than realm and token.

Parameters

• base_url str, default 'https://api.quickbase.com/v1'
  The API root. Must use HTTPS, except for loopback addresses.
• retry RetryPolicy | None, optional
  How to retry rate limits, connection failures, and reads that time out or get a 502, 503, or 504. A write isn't retried after anything that may have reached Quickbase.
• timeout float, default 30.0
  Seconds to allow for each step of a request, such as connecting or waiting for the response, as httpx applies it. Ignored if you pass http_client.

6 more: user_agent, http_client, schema_ttl, policy, confirmation_key, token_env

• user_agent str | None, optional
  Identifies your application, placed before the SDK's own User-Agent.
• http_client httpx.Client | None, optional
  Your own configured httpx client, for proxies, custom TLS, event hooks, or custom transports. You remain responsible for closing it.
• schema_ttl float, default 300.0
  Seconds to cache app, table, and field metadata. Use 0 to disable caching.
• policy Policy | BoundPolicy | None, optional
  What the client may do, as a BoundPolicy from Policy.bind(), or a Policy that names no table or field, such as Policy.read_only(). Every request is checked before it's sent, including through request(), and a refused one raises PolicyRefusedError. What the policy hides is left out of every response, so a hidden field acts as if it didn't exist. Without one, the client does whatever the token can.
• confirmation_key bytes | None, optional
  The secret that signs the confirmations an operation's preview returns, at least 32 random bytes, such as from secrets.token_bytes(32). Give several clients, or processes, the same key so that any of them accepts a preview another made. Without it, each client makes its own.
• token_env str, default 'QB_USER_TOKEN'
  The name of the variable that holds the token, for a program that has several.

Returns Quickbase

A new client.

Raises

• ConfigurationError: A variable is missing or empty, or an option can't be used.

from_env(
    *,
    base_url: str = "https://api.quickbase.com/v1",
    retry: RetryPolicy | None = None,
    timeout: float = 30.0,
    user_agent: str | None = None,
    http_client: httpx.Client | None = None,
    schema_ttl: float = 300.0,
    policy: Policy | BoundPolicy | None = None,
    confirmation_key: bytes | None = None,
    token_env: str = "QB_USER_TOKEN",
) -> Quickbase

Example

SyncAsync

from pyquickbase import Quickbase, Policy

with Quickbase.from_env(
    policy=Policy.read_only()
) as qb:
    app = qb.app("bq1234567")
    print(app.id)

from pyquickbase import AsyncQuickbase, Policy

async with AsyncQuickbase.from_env(
    policy=Policy.read_only()
) as qb:
    app = qb.app("bq1234567")
    print(app.id)

Output

bq1234567

Close a client

Close connections. Safe to call more than once.

The async client calls this aclose().

close() -> None

Example

SyncAsync

from pyquickbase import Quickbase

client = Quickbase(realm="acme", token="your_user_token")
try:
    print(client.realm)
finally:
    client.close()

from pyquickbase import AsyncQuickbase

client = AsyncQuickbase(realm="acme", token="your_user_token")
try:
    print(client.realm)
finally:
    await client.aclose()

Output

acme.quickbase.com

Use a client

For the full picture, see Configuring clients.

Get an app

Get an app by ID, the bq... part of its URL. This makes no network calls.

Parameters

• app_id str, required
  The app's ID, which contains only letters and numbers.

Returns App

An App. An ID that doesn't exist only fails on first use.

Raises

• ConfigurationError: app_id contains anything but letters and numbers.

app(app_id: str) -> App

Example

SyncAsync

app = qb.app("bq1234567")
print(app.id)

app = qb.app("bq1234567")
print(app.id)

Output

bq1234567

The client's realm

The full realm hostname, such as acme.quickbase.com.

realm: str

Example

SyncAsync

print(qb.realm)

print(qb.realm)

Output

acme.quickbase.com

The client's policy

The client's current policy. Creating a table replaces it with one that knows the table, so save this one with to_json() to use it elsewhere.

policy: BoundPolicy | None

Example

SyncAsync

from pyquickbase import Quickbase, Policy

read_only = Policy.read_only()
with Quickbase.from_env(policy=read_only) as qb:
    print(qb.policy.created)

from pyquickbase import AsyncQuickbase, Policy

read_only = Policy.read_only()
async with AsyncQuickbase.from_env(policy=read_only) as qb:
    print(qb.policy.created)

Output

()

Clear the metadata cache

Forget cached metadata, for example after changing a table's fields.

Use this after a change made outside this client, such as in the Quickbase interface. The client's own schema methods keep the cache current.

clear_schema_cache() -> None

Example

SyncAsync

qb.clear_schema_cache()

qb.clear_schema_cache()

Call any endpoint

Call any Quickbase endpoint directly and return its decoded JSON body.

This is the escape hatch for endpoints without a dedicated method. The client's retries and its policy still apply.

Parameters

• method str, required
  The HTTP method, such as GET.
• path str, required
  The endpoint, relative to the API root, such as /tables/abc123.
• params Mapping[str, Any] | None, optional
  Values to send in the query string.
• json Any, optional
  The value to send as the JSON body.

Returns Any

The decoded JSON body, or None if the response is empty.

Raises

• PolicyRefusedError: The client's policy doesn't allow this request. It wasn't sent.
• APIError: Quickbase returned an error. This is a subclass such as NotFoundError or PermissionDeniedError, for the status it returned.

request(
    method: str,
    path: str,
    *,
    params: Mapping[str, Any] | None = None,
    json: Any = None,
) -> Any

Example

SyncAsync

body = qb.request("GET", "/apps/bq1234567")
print(body["id"])

body = await qb.request("GET", "/apps/bq1234567")
print(body["id"])

Output

bq1234567

Create an app

For the full picture, see Working with apps.

Create an app

Create an empty app and return it. Use app.copy() to start from another app.

Parameters

• name str, required
  The app's name. Quickbase allows several apps with the same name.
• description str | None, optional
  The app's description.
• assign_token bool, default True
  Let this client's token reach the app, which a token limited to some apps can't otherwise do.

Returns App

An App for the new app.

Raises

• InvalidValueError: name is empty. Nothing was sent.
• PermissionDeniedError: The token's user can't create apps in this realm.
• PolicyRefusedError: The client has a policy, which covers one app. Nothing was sent.

create_app(
    name: str,
    *,
    description: str | None = None,
    assign_token: bool = True,
) -> App

Example

SyncAsync

app = qb.create_app(
    "Field Jobs", description="Crews, sites, and tasks"
)
print((app.info()).name)

app = await qb.create_app(
    "Field Jobs", description="Crews, sites, and tasks"
)
print((await app.info()).name)

Output

Field Jobs