Python

operate-as is the official Python library. It needs Python 3.9 or newer and has no dependencies beyond the standard library. Each service's actions come typed in a package of their own, such as operate-as-sheets: install the ones you use.

Get startedCopy Anchor Link

pip install operate-as operate-as-sheets

export OPERATE_AS_API_KEY="oa_..."

import os

from operate_as import OperateAs

operate = OperateAs(os.environ["OPERATE_AS_API_KEY"])

reporting = OperateAs(os.environ["OPERATE_AS_REPORTING_KEY"])  # reads sheets for the weekly report
bookings = OperateAs(os.environ["OPERATE_AS_BOOKINGS_KEY"])  # writes to one client's calendar

from operate_as_sheets import Sheets

miller = operate.client("6f1c2a7e-...")  # one of your clients, by id
rows = Sheets(miller).read_rows(spreadsheet_id="1BxiM...", range="A1:D20")
print(rows.status, rows.data["values"])

for client in operate.clients.list():
    print(client.id, client.name, client.services)
    # 6f1c2a7e-... Miller Dental ['sheets', 'slack']

OptionsCopy Anchor Link

operate = OperateAs(
    os.environ["OPERATE_AS_API_KEY"],
    base_url="https://api.operate.as",  # or set OPERATE_AS_BASE_URL
    timeout=60,                          # seconds, the default
)

Service packagesCopy Anchor Link

Every service with actions has a typed package: operate-as-<service> on PyPI, imported as operate_as_<service>. Its class takes a client and has each action as a method:

from operate_as_ai_inbx import AiInbx
from operate_as_sheets import Sheets

miller = operate.client(client_id)

AiInbx(miller).reply_to_email(
    email_id=email_id,
    body={"from": "kate@millerdental.com", "html": "<p>Thanks for booking!</p>"},
)
rows = Sheets(miller).read_rows(spreadsheet_id="1BxiM...", range="A1:D20")

Inputs are keyword arguments and bodies are TypedDicts, each documented, so your editor completes them and Pyright or mypy flags a missing or misspelled one. An input named like a keyword gets a trailing underscore, such as from_. Each class also has request() for any endpoint of the service's own API.

Each integration's page in these docs names its package. A package's version moves on when its service's actions change; it works with any operate-as of the same minor version. Without a package, client.service("sheets").run("read_rows", inputs) runs any action.

Actions and pass-throughCopy Anchor Link

sheets = Sheets(operate.client(client_id))
rows = sheets.read_rows(spreadsheet_id="1BxiM...", range="A1:D20")
print(rows.status)          # 200: the service's own status
print(rows.data["values"])  # the service's own response

The resultCopy Anchor Link

Every action and request return a Result:

When the service answers with a file, result.encoding is "base64" and data is the file as a base64 string. Decode it with base64.b64decode(result.data). encoding is "json" for parsed JSON and "text" for plain text. See The result.

result = sheets.read_rows(spreadsheet_id="1BxiM...", range="A1:D20")
if not result.ok:
    print("Sheets said no:", result.status, result.data)

ErrorsCopy Anchor Link

Every exception is an OperateAsError:

Any other status raises a plain OperateAsError. Every error has:

Catch reconnect-requiredCopy Anchor Link

A client's access ending won't fix itself. Catch it, tell someone, and stop working for that client:

import time

import operate_as

try:
    sheets.add_row(spreadsheet_id="1BxiM...", range="A1", values=["2026-10-16", "Jane Doe"])
except operate_as.ReconnectRequiredError as error:
    notify_team(f"{client_id}: {error.detail}")  # "...Send them their link to reconnect."
    pause_workflow(client_id)
except operate_as.RateLimitError as error:
    time.sleep(error.retry_after or 60)
except operate_as.ServiceError:
    retry_later()
except operate_as.OperateAsError as error:
    print(error.status, error.detail)

See Retries for what's worth retrying.

Verify webhooksCopy Anchor Link

Webhook.verify checks the Operate-As-Signature header and returns the event as a dict. Pass the raw body, before any JSON parsing:

import os

from flask import Flask, request
from operate_as import SignatureVerificationError, Webhook

app = Flask(__name__)


@app.post("/hooks/operate-as")
def operate_as_hook():
    try:
        event = Webhook.verify(
            request.get_data(),  # the raw bytes
            request.headers.get("Operate-As-Signature"),
            os.environ["OPERATE_AS_WEBHOOK_SECRET"],  # whsec_...
        )
    except SignatureVerificationError:
        return "", 400

    if event["type"] == "connection.expired":
        data = event["data"]
        email_client(data["clientName"], data["reconnectUrl"])
    return "", 204

See Webhooks for the events.

TypingCopy Anchor Link

The package ships type hints and is checked with Pyright in strict mode. Action, ActionInput, ActionPage and Result are frozen dataclasses. Client is one of your clients, with service(name) to act for it; ConnectedClient, from operate.clients, adds name and services. Result.data is Any, so narrow it yourself:

from typing import TypedDict


class ValueRange(TypedDict):
    range: str
    values: list[list[str]]


rows = sheets.read_rows(spreadsheet_id="1BxiM...", range="A1:D20")
values: ValueRange = rows.data