Pre-release

This release is a pre-release and may not be stable for production use.

openmates

Python SDK for OpenMates: run app skills, create encrypted chats, inspect usage, and automate everyday OpenMates tasks from Python.

OpenMates | SDK docs | Source

Install

pip install openmates

Install the latest prerelease from the dev channel:

pip install --pre --upgrade openmates

Quick Start

Open OpenMates.
Go to Settings > Developers > API Keys.
Create an API key with the scopes and credit limit your script needs.
Copy the key immediately. OpenMates only shows it once.

Set the key in your environment:

export OPENMATES_API_KEY="sk-api-..."

Run your first request:

from openmates import OpenMates

om = OpenMates()  # reads OPENMATES_API_KEY

result = om.apps.web.search({
    "requests": [{"query": "OpenMates SDK examples"}],
})

print(result)

SDK methods authenticate lazily. You do not need to call connect().

New SDK devices may need approval in Settings > Developers > Devices before they can access encrypted account data.

Common Examples

Send a private chat message

By default, chats.send() creates a non-persistent chat. It does not save the transcript to your OpenMates account.

response = om.chats.send("Summarize this release note draft.")
print(response.content)

Save the chat explicitly when you want it in your account history:

response = om.chats.send(
    "Draft a checklist for launching our beta.",
    save_to_account=True,
)

List and load encrypted chats

latest_chats = om.chats.list(limit=10)
chat = om.chats.load(latest_chats[0]["id"])

print(chat["chat"].get("title"))

Pass limit=0 only when you intentionally want all account chats.

Search the web

search = om.apps.web.search({
    "requests": [
        {"query": "privacy-first AI assistants", "count": 5},
    ],
})

Read a web page

page = om.apps.web.read({
    "url": "https://openmates.org/docs/user-guide/developers/sdk",
})

Search OpenMates docs

docs = om.docs.search("API keys")

Check billing and usage

overview = om.billing.overview()
invoices = om.billing.invoices()

Work with memories

memory_types = om.memories.types()
saved_memories = om.memories.list(app_id="web")

Create reminders

reminder = om.reminders.create({
    "title": "Review OpenMates SDK usage",
    "due_at": "2026-07-10T09:00:00Z",
})

SDK Areas

Namespace	Purpose
`om.apps.*`	Generated app-skill methods such as `web.search`, `web.read`, `images.generate`, `pdf.search`, and more.
`om.chats.*`	Encrypted chat list/load/send/export/share/delete helpers.
`om.docs.*`	Search OpenMates documentation.
`om.billing.*`	Usage overview, invoices, and billing metadata.
`om.account.*`	Account info, interests, storage, export helpers.
`om.memories.*`	List, create, update, and delete encrypted memory entries when your API key has memory scopes.
`om.reminders.*`	Create, list, and manage reminders.
`om.connected_accounts.*`	Import connected-account data with explicit user approval flows.
`om.embeds.*`	Inspect and share embed data when available to the API key.
`om.settings.*`	Update supported account settings such as language, theme, model defaults, and chat auto-delete.

Generated app-skill methods follow the app and skill names from OpenMates. For example, the web search skill is om.apps.web.search(...) and PDF search is om.apps.pdf.search(...).

API Keys and Scopes

API keys are bearer credentials. Treat them like passwords.

Store keys in environment variables or a secret manager.
Do not commit keys to source control.
Use the narrowest scopes and credit limits your script needs.
New SDK devices may require approval before they can access encrypted account data.

Common scopes include:

Scope	Allows
`chat:create_incognito`	Non-persistent SDK chats.
`chat:create_saved`	Saved account chats.
`chat:read_existing`	Listing and loading existing encrypted chats.
`chat:append_existing`	Adding messages to existing saved chats.
`chat:share`	Creating share links.
`memory:read`	Reading memory entries selected by the SDK caller.

App-skill scopes can allow all apps, a specific app, or a specific skill such as web:search.

Error Handling

from openmates import OpenMates, OpenMatesApiError, OpenMatesConfigError

try:
    om = OpenMates()
    print(om.billing.overview())
except OpenMatesConfigError as error:
    print(f"Configuration error: {error}")
except OpenMatesApiError as error:
    print(f"API error {error.status_code}: {error.data}")

The SDK raises:

OpenMatesConfigError for missing API keys or local key-unwrapping problems.
OpenMatesApiError for API responses such as expired keys, unapproved devices, missing scopes, or exceeded credit limits.

Versioning

OpenMates shows the short product line, for example v0.17, in the web app. Python package artifacts use exact release-line versions:

0.17.0aN is an alpha prerelease from the dev branch.
0.17.0 is a stable release from main.

Install stable releases with pip install openmates. Install prereleases with pip install --pre openmates.

Release files for openmates 0.17.0a12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openmates 0.17.0a12
File	Size	Uploaded
openmates-0.17.0a12.tar.gz	145.0 kB	Aug 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for openmates 0.17.0a12
File	Interpreter	ABI	Platform	Reset
openmates-0.17.0a12-py3-none-any.whl 109.7 kB Aug 29, 2026	Python 3	none	any	Details

Total release size: 254.7 kB

Release files / openmates-0.17.0a12.tar.gz

Download URL	openmates-0.17.0a12.tar.gz
Size	145.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`8864cd976ae8159ede33b279b254fa578a695c9395660937eba6fe50bcb406d7`
BLAKE2b-256 checksum How to use checksums	`4219cb2a0c4bfbe57660093b4efdb81be52ea475511dda729043ac4855d2bc64`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/glowingkitty/OpenMates
Publishing commit: github.com/glowingkitty/OpenMates/tree/4292a23cbc59b190c44d254c8117003fb44921e1

Workflow

Publishing configuration: github.com/glowingkitty/OpenMates/blob/4292a23cbc59b190c44d254c8117003fb44921e1/.github/workflows/publish-python-sdk.yml
Publishing logs: github.com/glowingkitty/OpenMates/actions/runs/33259646171/attempts/1

Artifact

Subject: openmates-0.17.0a12.tar.gz
SHA-256 checksum: 8864cd976ae8159ede33b279b254fa578a695c9395660937eba6fe50bcb406d7 Verifying attestations

Release files / openmates-0.17.0a12-py3-none-any.whl

Download URL	openmates-0.17.0a12-py3-none-any.whl
Size	109.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`329df48f8cb9a6a0fba7772159abe124ff97bcc8e5003c4014b881ae2f24c757`
BLAKE2b-256 checksum How to use checksums	`ed68137692c65425d3871359c774ba6f196a67a84ceb4996c22b589fc1da1a68`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/glowingkitty/OpenMates
Publishing commit: github.com/glowingkitty/OpenMates/tree/4292a23cbc59b190c44d254c8117003fb44921e1

Workflow

Publishing configuration: github.com/glowingkitty/OpenMates/blob/4292a23cbc59b190c44d254c8117003fb44921e1/.github/workflows/publish-python-sdk.yml
Publishing logs: github.com/glowingkitty/OpenMates/actions/runs/33259646171/attempts/1

Artifact

Subject: openmates-0.17.0a12-py3-none-any.whl
SHA-256 checksum: 329df48f8cb9a6a0fba7772159abe124ff97bcc8e5003c4014b881ae2f24c757 Verifying attestations