Python SDK

Create databases, manage scopes, and issue tokens. The SDK returns connection URLs. You connect to databases with your own client library (redis-py, neo4j, requests, etc.).

Install

pip install cinchdb

Initialize

from cinchdb import Cinch

# API key mode: full account access
client = Cinch(api_key="ck_live_...", org="acme")

# Scope token mode: scoped access for agents
agent = Cinch(scope_token="cinch_...")

✓

Environment variables

Set CINCH_API_KEY, CINCH_ORG, CINCH_ENV, CINCH_PROJECT to avoid passing credentials in code.

Configuration

client = Cinch(
    api_key="ck_live_...",
    org="acme",
    default_environment="production",  # or CINCH_ENV
    default_project="api",             # or CINCH_PROJECT
    timeout=30.0,                      # request timeout (seconds)
    max_retries=3,                     # retries for transient failures
)

Scopes

# Get or create a scope (idempotent)
scope = client.scope("my-scope", environment="production", project="api")

# List scopes
scopes = client.scopes(environment="production", project="api")

# Create a child scope
child = scope.create_scope("subtask")

# Issue a token for this scope
token = scope.token(permission="write", expires_in_days=7)
# Returns: {"token": "cinch_...", "scope_id": "...", "permission": "write"}

# Delete scope and everything in it
scope.delete()

Databases

# Create a database
db = scope.create_database(type="redis", name="cache")
# type: "redis", "sql", or "graph"

# Get an existing database (raises NotFoundError if missing)
db = scope.database(name="cache", type="redis")

# List all databases in this scope
dbs = scope.databases()

# Get connection URL
url = db.url()
# str(url)   -> full URL (pass to client libraries)
# print(url) -> redacted URL (safe for logs)

# Force refresh cached URL
url = db.url(force_refresh=True)

# Get DB token and env vars
db.db_token    # "cinch_..."
db.env_vars    # {"CINCH_DATABASE_URL": "https://...", "CINCH_DB_TOKEN": "cinch_..."}

No auto-creation

scope.database("name") only looks up existing databases. It raises NotFoundError if the database does not exist. Use scope.create_database() to create one first.

Scope token mode

When initialized with a scope token, use the scope-auth methods:

agent = Cinch(scope_token="cinch_...")

dbs = agent.scope_auth_databases()
db = agent.scope_auth_database("database-id")
scopes = agent.scope_auth_scopes()
scope = agent.scope_auth_scope("scope-name")

Error handling

from cinchdb import (
    CinchError,             # base class for all errors
    AuthenticationError,    # 401: bad key or token
    ForbiddenError,         # 403: insufficient permissions
    NotFoundError,          # 404: database or scope not found
    ValidationError,        # 400: invalid request
    ConflictError,          # 409: already exists
    ApiError,               # 5xx: server error (retried automatically)
    TimeoutError,           # request timed out (retried automatically)
    NetworkError,           # connection failed (retried automatically)
    RetryExhaustedError,    # all retries failed
    CircuitBreakerOpenError,  # API unreachable
)

try:
    db = scope.database("missing")
except NotFoundError:
    db = scope.create_database(type="redis", name="missing")

Server errors, timeouts, and network errors are retried automatically with exponential backoff (1s, 2s, 4s). All errors include trace_id for debugging.