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.16, in the web app. Python package artifacts use exact release-line versions:

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

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openmates-0.16.0.tar.gz (138.8 kB view details)

Uploaded Aug 22, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

openmates-0.16.0-py3-none-any.whl (104.3 kB view details)

Uploaded Aug 22, 2026 Python 3

File details

Details for the file openmates-0.16.0.tar.gz.

File metadata

Download URL: openmates-0.16.0.tar.gz
Upload date: Aug 22, 2026
Size: 138.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openmates-0.16.0.tar.gz
Algorithm	Hash digest
SHA256	`13bcff67dbfb62c1445e867ccf7a40bc544513367d300d910ba828871f485d92`
MD5	`f153789c9571afa6c9072bb398580c85`
BLAKE2b-256	`a7363074fd7241d52fe5b58675d924209c3f1a7c7948051df80173bee8f6be88`

See more details on using hashes here.

Provenance

The following attestation bundles were made for openmates-0.16.0.tar.gz:

Publisher: publish-python-sdk.yml on glowingkitty/OpenMates

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: openmates-0.16.0.tar.gz
- Subject digest: 13bcff67dbfb62c1445e867ccf7a40bc544513367d300d910ba828871f485d92
- Sigstore transparency entry: 2564064483
- Sigstore integration time: Aug 22, 2026
Source repository:
- Permalink: glowingkitty/OpenMates@0195d343dfc71ad0a03036be453356accf5f1f18
- Branch / Tag: refs/heads/main
- Owner: https://github.com/glowingkitty
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python-sdk.yml@0195d343dfc71ad0a03036be453356accf5f1f18
- Trigger Event: push