openmates
Your agentic operating system for everyday tasks, learning & work. With user interests & privacy first.
Python SDK for OpenMates: run app skills, create encrypted chats, inspect usage, and automate everyday OpenMates tasks from Python.
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:
OpenMatesConfigErrorfor missing API keys or local key-unwrapping problems.OpenMatesApiErrorfor API responses such as expired keys, unapproved devices, missing scopes, or exceeded credit limits.
Versioning
OpenMates shows the short product line, for example v0.19, in the web app.
Python package artifacts use exact release-line versions:
0.19.0aNis an alpha prerelease from thedevbranch.0.19.0is a stable release frommain.
Install stable releases with pip install openmates. Install prereleases with
pip install --pre openmates.
More Documentation
1 maintainer
Release files for openmates 0.19.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| openmates-0.19.0.tar.gz | 155.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openmates-0.19.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 273.0 kB
Release files / openmates-0.19.0.tar.gz
| Download URL | openmates-0.19.0.tar.gz |
|---|---|
| Size | 155.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1d34fe9df448443b47ef2f0b4a97f1e28d8b35890220e757fa11245fb1e74e60
|
|
BLAKE2b-256 checksum How to use checksums |
c6aab145e345b1182a124453bdf5790a911c9de2edeac2c6cc0fab42221b8bc8
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logRelease files / openmates-0.19.0-py3-none-any.whl
| Download URL | openmates-0.19.0-py3-none-any.whl |
|---|---|
| Size | 117.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9df807f9277fb3b16e5edb1f9b6b9a70aa0c189ae770dd6670f7cf9373e42625
|
|
BLAKE2b-256 checksum How to use checksums |
67aef62ea164551c4661189c2edc1fb26cb2b96d8805b0f30a611c72ce9b8e23
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency log
